Re: About OpenJade and Debian

[Adam Di Carlo <adam@xxxxxxxxxxx>]

[Note: Didier, would it be possible for you to start citing responses
in a more standard style, such as prepending "> " at the start of the
line?  This helps when trying to unravel several levels of citation,
cutting and trimming out...]

"Didier PH Martin" <martind@xxxxxxxxxxxxx> writes:

> Didier says:
> -----------------------------------------------
> Yes but it was for me. Now I now that Debian accept documentation written in
> *whatever. So, it will be ok if we provide the documentation for OpenJade in
> HTML :-)

Ah.... that's a good question.  It is Debian Policy that all programs
should have a man page.  Man pages are just short reference
documentation, generally just giving an overview of cmd-line
arguments, env vars used, config files, etc.

General documentation is fine to stay in HTML format.

Best solution IMHO is to use docbook2x to store XML or SGML versions of
manual entries (RefEntry) and burst that out into HTML/ROFF as well
for people who are boot-strapping.

Alternatively, we could just have the man pages point to the stock
HTML documentation, althought that is rather imcomplete in that it
doesn't talk about spam command line switches and all that.

> Didier says:
> ----------------------------------------------
> Adam, can you send me a copy of a document written in debiandoc (with DTD,
> etc...) So that I can take a look at it and make a DSSSL script.

Ok...  A pretty simple one can be found at
<URL:http://va.debian.org/~aph/developers-reference/developers-reference.sgml>
Get 'version.ent' from the same dir.

> If you promise me that if it does the job you'll use it instead of
> Perl/SGMLspm ;-)

I can't really make that promise, but I do promise we'll look at that
seriously.  The only real problem with using jade is that the ASCII
backend, while 'OK' if done with nochunks and lynx -dump -nolinks, is
not as good as the output we have with SGMLspm.

I *do* promise that if I like the way the DSSSL file is done (i.e.,
nice code techniques) then I will take that over and maintain
it... how about that?  Good enough promise?

> No doubts about it. The point is: it would be fun if part of (or the
> totality) the Debian documentation would be worked with DSSSL. ;-). So, you
> send me a debiandoc document (with DTD etc...). Norman did already the job
> for docbook (thank Norman for your contribution).

Yeah -- I have some plans too where debian would maintain a collective
bookmark list and set of URNs as well, with document metadata, making
a consistent documentation framework.  Some of my thoughts on that can
be found at <URL:http://va.debian.org/~aph/debian-metadata.html/>.

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


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist