Documentazione con immagini - qual è l'approccio più git-friendly? [chiuso]

Question

Documentazione con immagini - qual è l'approccio più git-friendly? [chiuso]

#1 da (4 voti)
#2 da (4 voti)
#3 da (1 voti)
#4 da (0 voti)
#5 da (0 voti)

2

Durante la documentazione del software, per tradizione, scrivo un file di testo semplice (come un README.txt) che funziona bene, ma sfortunatamente non può contenere immagini come HTML. Sfortunatamente le immagini devono essere archiviate come file separati con un normale documento HTML (usando < a href="... / foo.png" >) che danno confusione inutile.

Il "Salva una singola pagina web" in Internet Explorer utilizza MIME HTML (MHTML) per salvare tutte le risorse all'interno di un singolo file. La necessità di dover utilizzare un browser per leggerlo, non è un ostacolo in questi giorni. A quanto pare Opera e Word supportano la modifica diretta di questi documenti.

Usiamo git per il nostro codice sorgente, quindi le differenze viste da git tra due modifiche degli stessi documenti non dovrebbero essere grandi per evitare l'uso non necessario del disco e diff diffettabili quando si guarda il documento al di fuori dell'editor MTHML.

Qual è il miglior editor HTML mainstream per la produzione di file MHTML git-friendly?

git word

posta Karl Bielefeldt 01.12.2011 - 14:53

fonte

5 risposte

Leggi altre domande sui tag git word

Come ridurre al minimo la perdita di dati durante il licenziamento di un programmatore? Come scegliere una licenza corretta per un progetto?

score 4 · Answer 1

Memorrei le immagini e il testo separatamente nel controllo del codice sorgente; in questo modo, anche se le tue immagini sono blob binari (e quindi non gestite in modo efficiente), non avrai molte piccole modifiche sui file binari, a patto di non modificare molto le immagini.

Scegli un formato sorgente di documentazione che soddisfi le tue esigenze - HTML, Markdown, DocBook, LaTeX, ecc. - e memorizzi solo i sorgenti (e le immagini che devi includere) nel controllo del codice sorgente. Quindi, proprio come con il codice stesso, si imposta un sistema di compilazione, che consente a chiunque di compilare la documentazione in un formato consumabile (probabilmente molti di essi, ad esempio HTML multi-file, MHTML, PDF) dai sorgenti.

score 4 · Answer 2

Sembra che tu stia presupponendo che MHTML sia l'unico modo di incorporare immagini in HTML. Sulla base del fatto che si tratta di un'ipotesi piuttosto che di un MHTML come requisito assoluto, suggerirei di utilizzare HTML e URI di dati . Ciò consente di modificare il testo e ottenere le differenze usando un editor di testo standard; se hai intenzione di modificare le immagini molto probabilmente vorrai un editor di testo che supporti l'en-decodifica in base 64. Notepad ++ ha un plug-in standard per farlo, e sono sicuro che anche altri editor saranno presi di mira dai programmatori.

Devo notare che non ho mai usato questo approccio per la documentazione, ma l'ho usato per app_offline.htm pagine.

score 1 · Answer 3

Se, per qualche motivo, non desideri assolutamente immagini esterne, potresti incorporare immagini in HTML come base64 ( ecco un convertitore online ).

Personalmente preferirei avere file HTML (o meglio, Markdown) con immagini separate e esportare / stampare in PDF se / quando viene richiesto un singolo file, che è più facile da mantenere.

score 0 · Answer 4

0

Perché non provare l'approccio con Markdown - in questo modo, puoi avere HTML con le immagini e il " originale "sarà ancora in semplice formato testuale, facile da diff.

risposta data 01.12.2011 - 15:07

fonte

score 0 · Answer 5

Usa il formato RTF. A differenza di DOC / DOCX non è né binario né compresso, quindi DIFFS abbastanza bene. Inserendo le immagini le mettiamo alla fine del file e fai riferimento all'interno, quindi è più facile da usare come controllo del codice sorgente.