[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Debian-List HOWTO

Jason Gunthorpe <jgg@ualberta.ca> writes:

> Is there any place on the web site for documents like this? I know we have
> a couple already and we really should have more (like something about
> GnuPG)

I have proposed an integration of the DDP (which collects status and
pointers to Debian documentation) with the website.  No comments nor
volunteers thus far.

I believe that integration would make it easier to present, maintain,
and package the information.

I include that message again.

.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>

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.


  * 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


  * 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


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:

      webpages/                          -- DDP web materials
      manuals.sgml/                      -- 
                   Makefile              -- top level Makefile
                   developers-reference/ -- document module, in debiandoc-sgml

* 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.
This will make the status tracking aspect of the web pages much more
maintable, eliminating the "treble-keying" of manuals we currently

  <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
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: