Quanto è meglio scrivere documentazione indirizzata sia a HTML che a PDF?

I convertitori Latex-to-html che ho visto in passato sono stati piuttosto orribili. La modifica di html non è divertente e sembra non tradursi bene nella pagina stampata. Come fanno gli altri a risolvere questo problema? I collegamenti agli esempi (sia pdf che html) sarebbero fantastici.

Aggiunto: Un’altra domanda simile è stata appena posta:

Quale linguaggio di formattazione dovrei usare per la documentazione del progetto

Per documentare il codice, consiglio anche Sphinx. ReStructured Text è bello perché è leggibile e in qualche modo marcato in chiaro, e può fare un buon lavoro convertendo in html e in pdf. Mi piace ancora LaTeX per certe cose. Io e mia moglie usiamo LaTeX per scrivere la nostra lettera di Natale, che spediamo via posta ordinaria. La versione pdf è piuttosto elaborata, con due colonne e intestazioni e piè di pagina. La versione html è più semplice. Mi converto con plastex. Esempi qui: http://fedibblety.com/annualReports

Non credo che nessun formato binario sia una buona scelta (Word) per qualsiasi tipo di documento che vorresti leggere tra 10 anni. Questa è una delle cose belle di LaTeX.

Sì, i convertitori LaTeX-to-HTML erano soliti succhiare (probabilmente hai provato LaTeX2HTML), ma ultimamente sono migliorati. Tex4ht è altamente configurabile e produce simpatici XHTML + CSS. Vedi anche altri convertitori .

Puoi anche usare Docbook , se puoi sopportare di scrivere in esso. Ci sono convertitori da DocBook sia in HTML che in LaTeX (o direttamente in PDF); un esempio di quest’ultimo è dblatex .

Vedi questo post: LaTeX vs Docbook .

Dopo molti anni di angosce e parecchie false partenze, sto per rivisitare questo, e darò una prova a Sphinx . Può generare HTML o LaTeX da testo ricostruito .

Spero che sarà un’opzione molto più “leggera” rispetto al DocBook completo, ma con molti dei vantaggi.

Puoi fare un passo indietro e usare qualcosa come DocBook e renderizzare in PDF tramite LaTeX e HTML direttamente dai file DocBook. In alternativa, Adobe Technical Communication Suite (Framemaker) consente di creare un documento in formato PDF e HTML. Vedi questo post per una carrellata su vari sistemi di documentazione tecnica.

PlasTeX sembra un bel convertitore di latex-to-html, anche se non l’ho provato da solo.

Il mio amico Rob Felty ha scritto un post sul blog esaltando le sue virtù: http://blog.robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter/

AsciiDoc sembra una possibilità interessante.

Questa è una scelta personale, ma il Latex in teoria è perfetto, ma in pratica è doloroso. Sto usando l’editor HTML VS.NET + modifica HTML raw quando ne ho bisogno.

Quindi penso che l’uso di un editor HTML WSIWYG sia la scelta migliore. Puoi sempre utilizzare un semplice strumento per convertirlo in PDF e puoi sempre modificare HTML quando hai bisogno di qualcosa di avanzato. Inoltre è più facile da mettere online quando ti serve.

È così che gestisco le mie documentazioni software e funziona perfettamente per me.

Leggi informazioni sul formato EPUB. Il suo formato di e-book. http://en.wikipedia.org/wiki/EPUB

Dal momento che la risposta che menziona Asciidoc è stata piuttosto breve su alcuni esempi, ecco alcune delle cose che stai cercando:

  • Un pdf generato con Asciidoc
  • Un cheatsheet con una side by side del markup Asciidoc e il risultato html.
  • Un elenco di pubblicazioni fatte usando Asciidoc, inclusi i libri di O’Reilly e la documentazione di git (per vedere entrambi i lati della scala utente).

Non sono sicuro che il latex sia davvero lo strumento migliore per questo. Il problema che si ha con il solito convertitore di latex in html è indicativo del problema: html è semplice e non è espressivo come il latex.

Se insisti su latex in html, fai attenzione ad usare un sottoinsieme limitato in grado di convertire in modo ragionevole.

Ho usato TeXinfo in passato e fa un buon lavoro. Ecco un esempio: http://yootles.com/api . Preferirei restare con LaTeX, invece di usare un’altra lingua.

Se tutto il resto fallisce potresti prendere un convertitore LaTeX in XML e scrivere un semplice foglio di stile XSLT per convertirlo in HTML, oppure creare un foglio di stile CSS e collegarlo direttamente al file XML.

Abbiamo utilizzato WebWorks ePublisher (www.webworks.com) che offre sia formati multipli a sorgente singola (stiamo utilizzando Word) che la possibilità di produrre in molti formati di output (l’output è disponibile in Adobe PDF e Guida in linea (.CHM) .

Abbiamo affrontato questo problema in un progetto accademico che riguardava il software Eclipse e abbiamo utilizzato il plastex per convertire Latex in HTML e la guida di Eclipse. Farlo funzionare è stato abbastanza difficile, ma il risultato finale è molto bello. Puoi vedere tutte e tre le versioni qui:

http://handbook.event-b.org/

Inoltre, poiché questo è un progetto aperto, sono disponibili il codice (script di compilazione). Abbiamo un sistema di generazione continua (Jenkins) che ricostruisce tutto quando viene effettuato il check in di Latex. Questo è particolarmente interessante, poiché i contributori non hanno bisogno di installare la toolchain sui loro sistemi. Controllano semplicemente il nuovo Latex e controllano sul server se l’HTML è stato prodotto correttamente. fonti:

http://sourceforge.net/p/rodin-b-sharp/svn/HEAD/tree/trunk/Handbook/org.rodinp.handbook.feature/

Il migliore, Michael

Non ho abbastanza punti per commentare, ma per rafforzare la risposta plastex, ecco il link di esempio plastex aggiornato:

http://robfelty.com/2008/03/19/finally-a-better-latex-to-html-converter

LaTeX? Sul serio? Non ero a conoscenza che qualcuno al di fuori del mondo accademico lo usasse ancora. Vorrei andare con HTML, che è ansible salvare come PDF dal browser web. Se devi davvero avere qualcosa di tipografico avanzato, usa invece Word – ha un modo per salvare in HTML (probabilmente non è pulito come vorrebbe), e puoi salvarlo come PDF con un plug-in gratuito (scaricabile separatamente) .

Oh, e non mi preoccuperei di usare cose come InDesign – sono eccessive. Inoltre, non preoccuparti di pagare per Acrobat Professional: sono disponibili soluzioni gratuite per zillion.