[PLUTO-ildp] Ancora su Debiandoc-sgml .... :-)

[Hugh Hartmann]

Un saluto "evanescente" si propaga a tutti i partecipanti alla lista .. :-))

Preso dal mio girovagare in rete alla ricerca di ulteriori informazioni 
su come importare immagini all'interno di un file sgml di debiandoc, mi 
sono imbattuto su questi testi relativi al DDP, Progetto sulla 
Documentazione Debian e, neanche a dirlo, sono emerse delle interessanti 
considerazioni .... :-))

Riporto prima il testo in italiano e, a seguire, quello in inglese:

> DDP Documentation Policy
> 
> Sono qui elencate le decisioni che sono state prese nella nostra mailing list
> e approvate dal nostro Documentation Manager, Susan G. Kleinmann.
>  
> 
>     * Tutti i manuali del Debian Documentation Project (DDP) saranno rilasciati 
>     sotto licenze DFSG-compliant, più adatte della GPL.
>        
> [...]
>        
>     * Useremo SGML formato dei sorgenti.
> 
> Notare che ciò non significa che gli utenti dovranno imparare SGML per proporre 
> cambiamenti ai nostri documenti. Accetteremo tutti gli altri formati come buoni. 
> Comunque, essi sarannno tradotti in SGML da qualcuno di Debian-Doc.
> 
> Le altre opzioni erano: LaTeX, HTML, Texinfo, e diversi altri formati minori.
>        
>     * Useremo debiandoc-sgml per i nostri documenti.
> 
> Le altre opzioni erano linuxdoc-sgml o DocBook. Linuxdoc non è più mantenuto; 
> DocBook è da molti giudicato come troppo grosso, complesso e difficile da 
> personalizzare.
>        
>     * Ogni documento avrà una sola persona come Maintainer (Manutentore) e 
> potrà anche avere altre persone come Co-Maintainers.
> 
> [...] 

Bene, ed ora quello in inglese:

> 3.1 Source file format
> 
> SGML is used as the source format for all manuals. Both SGML format compatible 
> with the debiandoc-sgml [6] tool chain (DTD version 1 or later) and Docbook [7] 
> (SGML or XML, the 4.1.2 version or later). For the time being the default article 
> style [8] might need to be used.
> 
> Note: To translate from debiandoc-sgml format to docbook-xml please obtain and 
> install latest tool from DDP CVS by:
> 
>       $ cd $HOME
>       $ echo 'export PATH="~/Debiandoc-to-docbook:${PATH}"'>> ~/.bash_profile
>       $ . ~/.bash_profile
>       $ export CVSROOT=:pserver:anonymous a cvs.debian.org:/cvs/debian-doc
>       $ cvs login
>       $ cvs co -d Debiandoc-to-docbook utils/debiandoc-to-docbook
>       $ cd Debiandoc-to-docbook
>       $ cd /some/debiandoc/sgml/source-directory/   # use of mc is easy way :)
> 
> This script translates from debiandoc-sgml to docbook-xml with an XSLT stylesheet. 
> Please read README and dd3xml.html in this archive for the details.
> 
> When to you use which format? Docbook needs not be the chosen always as the only 
> documentation format. Debiandoc-sgml is preferred for most manuals since:
> 
>     * it's simpler (46 elements versus 300+) and thus easier to use.
> 
>     * output is (currently) better for some purposes, it is also more consistent 
>       (due to simplicity of the DTD).
> 
>     * it's a tool that has been used for all previous Debian manuals.
> 
> However, the debiandoc-sgml DTD does have some drawbacks including:
> 
>     * it is not possible to include images (see Bug #140684) or tables 
>       (see Bug #141727)
> 
>     * it is not internationalized completely (see Bug #31266)
> 
>     * there are some layout issues when generating some formats.
> 
> So, stick with debiandoc-sgml unless you need tables, figures, optional framed 
> output and such.
> 
> The other options for the source file format were: LaTeX, HTML, texinfo, groff 
> and several other minor formats. Even if some of these were used at some point 
> by DDP documents their use is not supported. All DDP manuals must be provided 
> either in debiandoc-sgml or docbook (sgml or xml) format (this rule does not 
> necessarily apply to other documentation that is handled by the DDP)
> 
> FIXME: Add links to relevant discussion on the mailing list, such as:
> 
>     * # DocBook vs. DebianDoc by John R. Daily
> 
>     * # debiandoc vs. docbook by Susan Kleinmann
> 
> FIXME: Discuss translation of documents and reference PO translation of debiandoc 
> documents and i18n and documentation (discuss needs of reviewers and translators).

Lascio a Giulio e a chi volesse partecipare alla discussione, ogni altra 
considerazione e commento.... :-)


Au Revoire
Hugh Hartmann