Re: debian-doc mailing list exists
On Fri, 28 Mar 1997, Jim Pick wrote:
> [I'm cc:'ing this to debian-devel also, to give interested parties
> enough time to sign up on the new list]
Ok, I'll continue this thread on debian-devel.
[snip]
> > a) To optimize the use of both the writers' time and the readers' time,
> > it will be necessary to exercise a high degree of interlinking, which is
> > not common to the HOWTO documents.
>
> I'd like to see a format where users would be encouraged to submit new
> documents that could easily be linked in to the documentation. I'd like
> to initially focus on generating on-line HTML (and text file) documentation.
> When we get a significant chunk of documentation written, then we can
> work on some other formats of documentation (like hardcopy) based on the
> content that we've already assembled.
I disagree here. Though I really don't like sgml much it seams to do a
very good job for the Linux HOWTO's as well as for our existing
documentation.
I see the following main advantages:
o you get several output formats at one time
o it very easy to have all documents us the same layout
o it's much easier to write the sgml code than to write html code
(you don't have to care about links, toc, etc.)
I have one question about debiandoc-sgml. It was built by Ian some time
ago when he was working on the dpkg prog manual and the policy manual. It
was split from linuxdoc-sgml since he saw several disadvantages of the
latter. I think he was right that time. However, it seams to me as
sgml-tools (successor of linuxdoc-sgml) has been worked on much lately and
I don't think it is appropriate for Debian to maintain its own SGML
system!
Susan, which system is your Debian FAQ based on?
Another option would by hyperlatex. Note that I took over maintainership
of this package because noone else wanted to do it. I didn't like this
very much but it seams to be doing a _very_ good job. What about writing
all docs in LaTeX and creating a HTML version via hyperlatex? (I'm a TeX
fan(atic) :-)
> > b) Eventually, the Debian WWW site, the Debian FAQ, the Debian documentation
> > system, (including the policy and programmer's manuals), the evolving
> > Debian FTP archives, and dwww should all work together and synergistically.
>
> I'm particularily interested in people's ideas for dwww, since I'm actively
> maintaining and developing it. In a day or two, I'll post some of my ideas
> for dwww, and we can discuss how it fits in with the overall design of
> the documentation. There are lots of issues: interfacing to the packaging
> system/menu system, internationalization, full text searching, plug-ins,
> etc. I'd also like to make it clear that dwww is basically an "open"
> package, and anybody who would like to contribute to it is welcome to.
> I'm planning to build a "plug-in" type of architecture into it so that
> anyone can build systems that work with it.
IMHO dwww is a _very_ important point of the Debian distribution. It seams
to me as the development of Debian now comes to a point where most
technical issues are solved (we have a good policy now, a good packing
format, etc.) so we should take the chance and spend more time in
improving the documentation of our system!
The Policy is very unclear about documentation (there is an open bug
report) and we certainly have to work on this. I think we should discuss
this issue on the new mailing list in the next days.
BTW, I'm currently working on restructuring the Policy Manual. These
issues will be discussed on debian-doc, too. However, any changes will be
presented and discussed on debian-devel afterwards. (But I encourage
everyone that wants to take part in the discussion to join the debian-doc
mailing list).
> > c) The Debian documentation should contain information customized for
> > the Debian system; it should not contain any details that are only
> > relevant to foreign systems. For example, if a Debian package <foo> is
> > set up so that when it's installed it will already have certain
> > configuration files or some default operation, then the user should just
> > be informed of that setup, rather than exposed to all of the possible
> > setups that he might consider.
>
> Yes. Sounds like a job for dwww.
>
> Personally, I was planning on developing a package containing my personal
> notes on the various Debian packages, and making it work as a "plug-in"
> for the dwww system. Perhaps this idea could be expanded so that anyone
> could contribute.
IMHO it would be nice to browse through dpkg's database with the web
browser similar to what dselect's doing now (but much more user
friendly!). One could list all available packages, see dependencies, have
additional links to upstream www pages, etc.
> > d) The Debian documents should be tunable (IMHO) to the user's needs, e.g.,
> > if he has all the documentation present on his own or a local system,
> > then links in his documentation should point to links on that local system,
> > except where external links are absolutely demanded. This idea will
> > need a lot of refinement in order to define _except_.
>
> I want to propose an addition to dpkg which would enable a user to install
> the documentation only from a package. I'd love to install the documentation
> for every Debian package on dwww.jimpick.com as a service to the Debian
> community.
>
> > These points need to be discussed and refined. Once that's done, then
> > we can begin to design the documents, set up some prototypes or examples,
> > and then (hopefully) divide the work.
>
> I don't know about assigning tasks to people, but if we provided an
> environment where people received credit and recognition for the work
> they do in providing documentation - similar in the way that we honour
> package developers - then I think people will contribute. Of course,
> we should also build an infrastructure that makes it easy.
Good point.
> > On the other hand, if this strikes readers as a bad way to proceed,
> > then please offer (on debian-doc) an alternative procedure.
>
> Sounds like a good start to me. :-)
Hey, I suspect we'll have much fun on this mailing list :-)
Cheers,
Chris
-- Christian Schwarz
schwarz@monet.m.isar.de, schwarz@schwarz-online.com
schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
CS Software goes online! Visit our new home page at
http://www.schwarz-online.com
Reply to: