[RFC] DDP and www.debian.org merger
The following is my plan on why and how to merge the DDP area with
www.debian.org, specifically, the Debian WML CVS area.
Comments are appreciated.
Overview:
* merge DDP web pages with Debian WML CVS area, devel/ddp
* retain existing manual sources in DDP CVS area
* setup autobuild of DDP working copies to devel/ddp/working-copies
Rationale:
* promote DDP web pages to standard www.debian.org makes the DDP
less of a marginalized splinter project
* exploit www.debian.org mirrors
* exploit current translation efforts on web pages
* use WML in conjunction with small doc description files to
produce a list of manuals and their locations which is much
easier to maintain
Description:
The DDP Web pages are currently maintained from the DDP CVS area; they
can be found at the web at <http://www.debian.org/~elphick/ddp/>.
The DDP CVS area currently has the following structure:
ddp/
webpages/ -- DDP web materials
manuals.sgml/ --
Makefile -- top level Makefile
developers-reference/ -- document module, in debiandoc-sgml
dictionary/
intro-i18n/
...
* DDP Web Pages
The function of the DDP web pages are to facilitate communication
between Debian documenters. It tracks status of manuals which are
released, being written, and tracks proposals for new manuals. It
describes how to access the DDP CVS area, policies and guidelines for
documenters. Working versions of manuals are presented.
Basically -- a clearing-house of information for Debian documenters.
Essentially, what I propose to do is eliminate ddp/webpages/* and
merge that into wml/english/devel/ddp/ . Making this move, I will
create small language neutral <document>.wmh files which will contain
status information which can be shared across translated languages.
**PROPOSED LOCATION OF THESE FILES REQUESTED FROM Debina WML GURUS**
This will make the status tracking aspect of the web pages much more
maintable, eliminating the "treble-keying" of manuals we currently
have:
<apharris@arroz:webpages> grep "Developer's Reference" *.html
index.html: <li><a href="manuals.html#devref">Debian Developer's Reference</a>
manuals.html: <li><a href="#devref">Debian Developer's Reference</a></li>
manuals.html: name="devref">Debian Developer's Reference</a></h2>
Disadvantage: disjunction between DDP and WML CVS areas; documenters
able to maintain manuals not able to update status. Practically,
however, this rarely happens.
* DDP Working Copies
Oliver, the past DDP leader, has his own cron-driven autobuilder
scripts which produce the HTML version of the manuals from their
DebianDoc-SGML sources. The top-level Makefile is very modular; all
subdirs recognize a special 'publish' target which builds HTML and
installs it according to the PUBLISHDIR target.
This system works very well; thus I propose to retain it. I would
move the autobuilder to master.debian.org (where www.debian.org is
mirrored from) and run a nightly 'cvs update -d' and 'make
PUBLISHDIR=/org/www.debian.org/debian.org/devel/ddp/working-copies
publish' (basically just Olly's modified cron script).
The cron script is run from a checked out copy. Since CVS now support
multiple CVSROOTs in one tree, I could also check out non-DDP CVS
modules such as Debian Policy and automatically publish that as well.
The benefits of this system is basically easy-to-access source and
built versions of unreleased manuals.
* Official Versions of Manuals
I do *not* propose to autobuild to official location on
www.debian.org, such as doc/ . This is definately doable, the only
problem is release management -- distinguishing between working copies
and released copies. The only way I can think of to do this
automatically would require the use of CVS tagging (such as
cvs-buildpackage style) and building from tagged CVS source. Even so,
there is a risk of divergance against the packaged manuals.
[ Other archive administrators (Guy) have proposed that dinstall be
modified to recognize certain 'ByHand' entries automatically and do
the right thing. ]
However, that area *could* be rationalized in its structure to mirror
the devel/ddp/working-copies structure. Moreover, the <document>.wmh
files could be used to provide a managable list of documentation.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: