Re: A very simple documentation framework
On Fri, Mar 02, 2007 at 10:37:52PM EST, ][ wrote:
> Sorry for responding late...
No problem.
I'm still working on it.
:-)
> On Sun, 11 Feb 2007 11:05:07 -0500, Douglas Allan Tutty wrote:
> > On Sun, Feb 11, 2007 at 06:11:58AM -0500, cga2000 wrote:
> >> So far my personal doc system amounts to a patchwork of notes and
> >> cheat sheets in ascii files that I grep when I need to find some piece
> >> of information or other.
> >>
> >> I would like to switch to something a little more ambitious where I
> >> would be able to generate my docs in the usual popular formats, namely
> >> pdf, html, ps, txt, and possibly dvi.
<snip>
> > I asked something similar a couple of months ago and the concensus was
> > either LaTex or DocBook.
>
> No, LaTex or DocBook would be too much over kill for simple documentation,
> though I'm very found of LaTex myself.
You're right, but it's difficult to resist learning at least the basics
of LaTeX and DocBook.
The risk, naturally, is that trying to kill two birds with one stone I
might miss both (writing the doc and learning the documentation tools)
.. and end up empty-handed.
> Check out AsciiDoc.
> Would something like this (AsciiDoc sample output)
> http://xpt.sourceforge.net/techdocs/misc/ce01-DarkBackgroundIsGoodForYou/
> be good enough? It fulfills all your requirement, but is even more simpler.
Definitely. I would add that due to their complexity, achieving the
same quality going down the LaTeX or the DocBook toolchains is probably not
going to be trivial.
A more subtle risk is possibly that considering that these two are such
large complex products and that since I lack the technical proficiency
(and likely the time to acquire it) .. I may have to stick to a such a
small subset of their respective capabilities that I would end up
limiting myself as a "writer". What I mean is that for instance, I
might want to present a given topic in a certain way but end up doing
differently only because I'd start thinking that it would take me days
(or weeks..) to figure out how to do it.
> If you don't believe that everything behind it was just plain text, check
> out the
>
> AsciiDoc Markup Syntax Quick Summary
> http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/
Actually, in my setup at least, the "Dark Background" document looks
absolutely great in a text browser such as elinks.
:-)
Maybe another concern of mine is that LaTeX and DocBook are technologies
that won't go away any time soon.. And this guarantees that both the
time I spend rewriting my .txt documents in either of these, and the
time spent acquiring some fluency using them is not entirely wasted.
Right now, my preference would probably be DocBook over LaTeX since it
clearly separates content and formatting. In my case it's not just a
matter of DocBook doing the "right" thing. An additional incentive is
that as long as I can find suitable stylesheets, I only need to become
fluent with a dozen or so xml tags to get started and the transformation
tools will take care of everything else for me.
I also saw somewhere that there seems to exist a simplified version of
DocBook. I know nothing about its current status, but I should probably
take a look and see it might do anything for me ..
Lastly, I'm also curious of DocBook's capabilities as far as providing a
framework that might (?) help locate information in what would amount to
a "documentation database". Here again, recursive grep's of my text
files usually works where my personal docs are concerned .. but in terms
of "concept", it's clearly not a very satisfying approach.
Maybe I'm more interested in documentation technology than the drudgery
of writing and maintaining documents.
:-)
In any case, thanks much for your comments.
Thanks,
cga
Reply to: