Re: A very simple documentation framework
On Sat, 03 Mar 2007 03:36:01 -0500, cga2000 wrote:
>> Check out AsciiDoc.
>> 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.
Have you check it out in GUI browsers as well, for the embedded images?
> 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...
Seems that I didn't make it quite clear. The above "AsciiDoc Markup Syntax
Quick Summary" shows how simple it is to produce stunning effects via just
plain text. In fact the source (for making the html or whatever) looks
nothing like any markup language but plain text. You almost don't need to
learn anything, well I mean the markup language -- just learn how to
format your text content.
Further, you can produce html or DocBook/LaTeX source from AsciiDoc, and
even *nix man pages.
All in all, check out
AsciiDoc
http://www.methods.co.nz/asciidoc/
and see if its simple formatting fits all your need for your simple
documentation framework, before submerging into something *much* more
complicated.
If it doesn't seem to meet all your need, I recommend to go directly to
Latex. Because the documents that you've seen on xpt.sourceforge.net and
AsciiDoc sites are actually produced by DocBook.
On xpt.sourceforge.net the separated pages with TOC is produced by
DocBook (from AsciiDoc source). The single file versions are produced
directly by AsciiDoc.
Check out the difference at
http://xpt.sourceforge.net/techdocs/nix/asciidoc-usg/ascu03-SourceCodeHighlighting/ar01s04.html#id2497513
and compare with the "single file version" link from the bottom of the
page.
If you do need Latex, then maybe the
All You Need to Know about Latex
http://xpt.sourceforge.net/techdocs/language/latex/
might give you somewhat easier start. That is in fact what all I need to
know when writing my master thesis.
HTH
--
Tong (remove underscore(s) to reply)
http://xpt.sf.net/techdocs/
http://xpt.sf.net/tools/
Reply to: