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

Documentation stuff


Sorry for being absent from most of the conversation, and not getting
my latest release of dwww out...  - I was working in Vancouver last 
week, came back, got sick, one of my main modems burnt out (lightning?),
I replaced it, upgraded my server, messed up PPP, didn't configure
the modem correctly, clients calling me up giving me more work, etc,
etc, etc...  - so I'm way behind schedule on dwww.

Here's my ideas for the documentation stuff:

1)  a web server, dwww, etc. should be optional - not a core part
    of the system.  I hope to fix up dwww so that it is much faster,
    powerful, nice, etc.  - but the HTML documentation should be
    browseable without having all this stuff installed.

    dwww is meant to integrate the existing documentation formats
    for convenience, but not replace all of them.

2)  All the documentation should be viewable via HTML if dwww is
    installed - but it shouldn't be necessary to have HTML versions
    of something that is already in info or man format.  If there is an
    HTML version that looks better, by all means include it (if
    it's small, put it in the same package, otherwise use a
    separate package).

3)  I'd recommend using something like Debiandoc-SGML for documentation
    written directly for Debian.  But this should be optional.  I like
    it because it will work nicely with dwww (and without), plus it is 
    fairly consistent, and can be converted to multiple formats.  We 
    discussed some nice enhancements for it on the debian-doc mailing 
    list which should work quite nicely.

    Oh yeah, we still need separate /usr/doc/<package>/README files,
    and man pages too...  HTML shouldn't be used to replace these.
    HTML shouldn't be used to replace info files shipped with GNU
    software either.

4)  HTML documentation, if it exists, should be gzipped.  Lynx and
    Netscape can handle the compressed files, provided that the links
    are straightened out using a tool like fixhrefgz.  I was going to
    stick that tool into a "dwww-dev" package + possibly some other
    ones.  (I've got a few Debian installations on 386's and 486's
    with less than 150MB of disk total)  - I'm going to experiment
    with straightening out the jdk1.1 documentation...

    e2compr isn't really an option, in my opinion, since it restricts 
    the portability of the entire system.   

5)  It would be nice if Diety could install just documentation, or
    just the binaries, and no documentation.

6)  dwww will let us serve documentation directly off of an external
    site, so it would be nice to have a way of installing the packages
    with no documentation at all.

7)  Cacheing - I'm going to split the cacheing in dwww into a separate
    package.  That way, it should be easy to improve it, not use it,
    or use something like squid instead.

That's it for now...


 - Jim

Attachment: pgppNyPNrd16g.pgp
Description: PGP signature

Reply to: