|
[Date Prev] [Date Next] [Thread Prev] [Thread Next] [Date Index] [Thread Index]
|
Re: [PLUG] documentation question from a while ago...
|
I had done a fair amount of documentation at work, some for software
some for just general stuff. I tried docbook, and while I found it
was quick to pick up and I liked the outputs, I felt limited by some
of the constructs. I was looking for something else. LaTeX was it.
So as with most things discussed on this list "there's more than one
way to do it." And all future documentation work that I do will be
done in TeX and LaTeX. I just put in my order for a copy of Knuth's
_The TeXbook_.
The main reasoning is the output is superb, you can get really
granular in the layout of individual pages if you choose to, or you
can use the default LaTeX macros article layout and focus on the
content rather than the look. And of course it was invented by Knuth.
If you want to get started with LaTeX, take a look at:
http://www.tug.org/interest.html
Tobi Oetiker's "The Not So Short Introduction to LaTeX" is most
certainly the place to start:
ftp://tug.ctan.org/tex-archive/info/lshort/english/lshort.pdf
But I don't intend to generate any other document which is destined
for a printer other than with TeX.
On or about Thu, May 23, 2002 at 08:37:45PM -0400, Kyle R . Burton wrote:
> I had asked for advice on what tools/technology to use for software
> documentation for an opensource project I'm involved with.
>
> Someone asked if I'd let them know what I finall decided on and why.
>
> Everywhere I looked, it seemed DocBook was king. There are alot of sites
> that recommend it, and I couldn't really find anyone who recommended against
> it. After looking into DocBook itself, and the bevy of tools, DTDs, DSSL
> style sheets and catlogs, that you're instructed to download, configure,
> and install, I got lazy and started looking for something easier.
>
> I figured that since Lyx purported to support docbook, and was a wysiwyg
> editor, that it would be the fastest way for me to get up and running.
> I could not get it to export to DocBook SGML or XML successfuly. It would
> either crash or not perform the export. Granted I'm using version 1.16
> that came with my Linux distribution (Mandrake), so I don't know if that's
> an issue -- I didn't pursue it.
>
> My failure to get Lyx to emit the documentation, and my personal bias of
> being comfortable with, and having a high performance level, with vim
> (which makes most other editors feel like they get in my way, and
> subsequently feel slow), lead me to stop using Lyx.
>
> That lead me back to DocBook. I went to linuxdoc.org and started reading
> the authors guide. I couldn't get the tools to build the sample documentation
> sgml files that came with the distribution!
>
> Then I came across a page (I think it was on CERN) that had an example
> where they used a tool called db2html. I hadn't seen that before. Looking
> on my system, it had been included when I installed Linux. The package it
> is part of is called sgml-tools. That suite of utilities (which includes
> db2ps and db2pdf) worked easily, and worked the first time. I wish I
> had found them first, I would have saved myself about a week of frustration.
>
>
> So now I'm having alot of success with DocBook. I'm finding that creating
> the documenation is easy, only slowed down by my ignorance of the DocBook
> tags. The generation of PDF, PS and interlinked HTML documentation is
> easy. The default templates and stylesheets are acceptable for the needs
> of the project - I know in the back of my mind that if need be we can
> create our own stylesheets and configure the system to emit whatever
> we want.
>
>
>
> At this point, I'd whole-heartedly recommend DocBook for anyone needing
> to create software documentation. Just remember sgml-tools. :)
>
>
> Best regards,
> Kyle R. Burton
>
>
>
>
>
>
>
> --
>
> ------------------------------------------------------------------------------
> Wisdom and Compassion are inseparable.
> -- Christmas Humphreys
> mortis@voicenet.com http://www.voicenet.com/~mortis
> ------------------------------------------------------------------------------
>
> ______________________________________________________________________
> Philadelphia Linux Users Group - http://www.phillylinux.org
> Announcements-http://lists.phillylinux.org/mail/listinfo/plug-announce
> General Discussion - http://lists.phillylinux.org/mail/listinfo/plug
______________________________________________________________________
Philadelphia Linux Users Group - http://www.phillylinux.org
Announcements-http://lists.phillylinux.org/mail/listinfo/plug-announce
General Discussion - http://lists.phillylinux.org/mail/listinfo/plug
|
|