Re: Where to start? (Newbie Q's)
> Hello all,
>
> Here I am, wanting to write some docs (or work on some that are already out
> there), and I can't find any decent documentation on how to write
> documentation! So, naturally, I've got a few questions:
>
> 1. I see that sgml is the way to go. But in my research of sgml, I don't get
> it: I know that it is a tag language like html, (okay, I actually know that
> html is a sub-set of sgml), but I don't know what the tags are.
>
> 2. I don't know what the difference is between DocBook and Debiandoc-sgml...
>
> 3. When downloading stuff via cvs, will that answer some of my questions?
>
> 4. I looked at my /usr/share/doc/sgml-stuff, but it isn't making too much
> sense to me. I'm getting the feeling that DSSSL is really how the markups are
> defined (?) But where would I find out what they are?
>
> 5. There must be 10 different environments for editing sgml. I realize that
> it's more a personal choice and so forth, but I'm wondering about all the
> formats and such...
>
I've been using emacs, it seems to be pretty powerful but with a steep
learning curve.
> Thanks for the help.
>
> Russell
>
Hi Russell,
I hang out here, too, hoping to get some insight.
As we find out stuff, we should collect the info we find is needed to do
this. Then, when we get done, we can contribute a document somewhere that
will help the next guy.
Adam's answer the other day sent me to
http://cvs.debian.org/boot-floppies/documentation/README-authors
I note that the install docs are in SGML (so XML is not appropriate at least
in that area, maybe for a new document). I also found the "make lint-docs"
command that Adam was referring to. This really didn't work for me, but I'm
still playing with it.
I saw in the Makefile which that runs
http://cvs.debian.org/boot-floppies/documentation/Makefile
that the nsgmls command that does the tag verification is
nsgmls -ges -wall /usr/lib/sgml/declaration/debiandoc.decl
so that path is probably the debiandoc dtd.
I haven't tried the command yet, nor looked at that file.
*----------------------------------------------------------------*
| .''`. | Debian GNU/Linux: <http://www.debian.org> |
| : :' : | debian-imac: <http://debian-imac.sourceforge.net> |
| `. `'` | . oo Chris Tillman |
| `- | ( -) tillman@azstarnet.com |
*----------------"--"--------------------------------------------*
Reply to: