Re: WIP: asciidoc replacement

[David Kastrup <dak@gnu.org>]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> On Wed, Oct 03, 2007 at 12:25:44PM +0200, David Kastrup wrote:
>
>> The problem is that we are not editing plain text, but Docbook
>> source masquerading as plain text.
>
> I do a fair amount of editing of the asciidoc source, but 99% of it
> is done by just blind imitation of what's already there.

But not everything is already there, and when something surprising
happens, there is little chance to see how it came about.

> Maybe my experience would be the same with Docbook--I have no idea,
> never having worked with it--but if you're suggesting that knowledge
> of Docbook is a prerequisite for working with asciidoc, that
> certainly hasn't been my experience.

"making use of" and "working with" are two different things.

>> But it is not all _all_ easily writeable the moment you try to do
>> something with _structural_ impact.  In fact, it is pretty much
>> impossible for anybody except wizards to do that.  And when the
>> wizards do it, they can't actually document what they have been
>> doing since that would mean cluttering the purported "plain text
>> documentation" with formatting comments.
>
> I'm not sure what you're talking about here.  Example?

Try including the manual pages as a (properly linked when man pages
are referenced) appendix in the user manual, so that the printed form
(or PDF) of the user manual is a single coherent document with all
information inside.  That's what I tried for about a week, digging
into the various available (and unavailable) documentation and then
postponing the project indefinitely because it both exceeded my
current capability as well as demonstrating that there was no
reasonably outlined path for acquiring the necessary skills.

In Texinfo, this takes few commands, all of which are well-documented
and in a reasonable place in the Texinfo manual (which is all you need
to consult in order to write Texinfo documents).

But with git's AsciiDoc information, not only is the required
information scattered through half a dozen of different manuals all
describing completely different systems, but the necessary other
documentation is, at best, only mentioned in passing in every single
relevant document.  So while you may know where you want to start and
end your journey, there is nothing which would tell you how to get
from start to end.  You have to randomly pick your road until you may
or may not find something closer to the end.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum