[RFP] A more maneagable way to include documentation

[Javier Fdz-Sanguino Pen~a <jfs@ieeesb.etsit.upm.es>]

This is a proposal based on the RFC sent from Adam Di Carlo to the
debian-www list october 8th 1999 (go to the mailing list archive to
read the discussion that took place see
http://www.debian.org/List-Archives/debian-doc-9910/msg00012.html).

We are currently in the DDP without a leader since Adam moved to the
boot-floppies team, I do not intend to become a leader for the project
I just want to make things happen :)

Currently there is no such thing as "visible" documentation in Debian,
yes, we have a DDP project, but save for bits of it maintainers are
willing to make packages to this documentation is not seen in the FTP
mirrors/official WWW site. We need to make our documentation more
visible for two reasons:

- users are not aware of it and so don't use it/send comments to it.
- to make more maintainers aware of the documentation part in Debian
and thus contribute to it in the project.

I will not go into details on how it currently is or how it should
change, my ideas are the same of Adams' (see above). However I do feel
we need some clear steps on what should we do in order to achieve this
goal.

The goal as it is would be:

- Have a www.d.o/devel/ddp section with the DDP pages and all the sgml
manuals. 

- Have a www.d.o/doc and ftp.d.o/doc section that includes *all*
finished documentation. Both directories should have the same stuff,
and this should be included in the official CD's.

        The following steps need to be made in order to achieve this:

1.- move DDP's web from elphick's home pages to Debian's wml. This is
an easy call, just touch the html files in order to make them wml with
a defined template.

2.- create a database of documents so the pages are automatically
updated and do not have to be manually edited. There are several
possibilites (and others I might not be aware of):

        - do it likewise of other things in the www
(vendor/consultants)
        - a hash array made in Perl, similarly to the ones used for
coordination in the French and Spanish translation teams (check for
example the scripts in international/spanish/)
        - wmh file?

3.- Study how can sgml and html/ps/txt copies of documentation that is
work in progress can be both in debian-doc's CVS area and debian-www's
WML are. There was talk of how CVS can have two CVSROOT
directories. We would need this and a Makefile (currently made in
debian-ddp) to update the documents from one debian-ddp to debian-ww
and publish it.
        Thus authors would still use debian-ddp's area and developers
could reach documents being worked on in
www.d.o/devel/ddp/manuals.{html,sgml,txt,ps}/

4.- Study how to include *finished* documentation in /doc.
Two ways:

        - using CVS tags (complicated and might need hacking)
        - using 'byhand' procedures in packages. Currently this
approach is used by maint-guide's packages. Maybe we could work in a
way to more automate the 'byhand' procedure maybe by giving info (in
'files' of where the files should be installed). This way we could
make packages of documentation using cvs-buildpackage and upload when
a finished version was ready. Also, the boot-floppies team could
make packages for the installation documentation rather than using
'rsync' from the Makefiles in the source as it is made now.

        Once all this is done we have achieved the goal stated above. 
Document authors and translators work would go like this:

document.sgml -> debian ddp's cvs -(co'd)-> 
        debian-www (devel/ddp/document.sgml) - (builds) -> document.html

In order to 'publish' the documents in the ftp site and w.d.o/doc I
suggest that using the debian-doc package source, we make a
multipackage with all the documentation considered "finished" and with
the appropiate calls to doc-base package, 'ala' maint-guide package.
        That way when building the debian-doc package we build/install
byhand the maint-guide, the debian-guide... The Debian DDP leader
would be the maintainer of this package.



        ¿Ideas? ¿Suggestions? ¿Volunteers? :) 

       Javi

PD: For information on how *currently* the DDP/boot-floppies is
working I suggest reading
http://www.debian.org/List-Archives/debian-doc-9910/msg00012.html and the
Makefile in the documentation directory of the boot-floppies
directory.