Re: A very simple documentation framework
On Sat, Mar 03, 2007 at 11:16:53AM EST, ][ wrote:
> On Sat, 03 Mar 2007 03:36:01 -0500, cga2000 wrote:
>
[..]
> >>
> >> AsciiDoc Markup Syntax Quick Summary
> >> http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/
A bit OT .. but what is this xpt project?
Apart from the AsciiDoc manuals, there tons of useful documents on this
web site.
> > 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?
They look ok, but I'm used to reading docs in text-mode and I find all
the different size fonts, colors, little icons, etc. distracting.
> > 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.
It's not really plain text. More like a cross of a simplified markup
language and a word processor. ie. the "tagging" is designed in such a
way as to be less obtrusive and in a sense even somewhat "wysiwg".
> 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.
In this respect, I really don't see much difference between AsciiDoc's
minimal syntax and using a minimal subset of LaTeX or DocBook.
There is naturally more to type, parcticularly with XML and its opening
and closing tags.. but then, I type reasonably fast and I'm sure there
has to be some Vim plugin that would help make life easier for me.
I admit that with AsciiDoc, source files are easier to read, especially
for someone unfamiliar with the syntax .. But then contrary to using a
subset of something much bigger such as LaTeX or DocBook, you're bound
to lose "scalability".
> Further, you can produce html or DocBook/LaTeX source from AsciiDoc, and
> even *nix man pages.
Saw that. See below.
> 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 you stick with a small subset neither LaTeX nor DocBook are *that*
hard to learn. My main problem, especially with DocBook, was finding
exactly what debian packages I needed to build working html/pdf tool
chains.
> 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.
You've lost me. Are you recommending LaTeX or 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.
Since I haven't found a tool that does that well, at least with my text
files, I may yet invest in AsciiDoc a bit because I have numerous doc
files in text format and I was wondering if it might help convert them
to DocBook format. Obviously, it won't do it out of the box but I have
a feeling that with minimal changes to my text files I may be able to do
that.
Thanks,
cga
Reply to: