Re: [A-a-p-user] Docbook notes
Brought to you by:
vimboss
From: Bram M. <Br...@mo...> - 2003-07-31 15:20:53
|
Jean Jordaan wrote: > > Well, these alternatives still require editing text in some kind of > > special format that makes you look in the docs about the detailed > > syntax. None of them is WYSIWYG. > > The problem is that WYS isn't WYG either ... Where *you* see two > headings, *Word* might see one Heading style line, and one Paragraph, > font size 16, font weight bold. Both look exactly the same, they're > meant to convey the same meaning, but they're different for > processing purposes. It's not difficult at all to use WYSIWYG in the correct way. Just use paragraphs with a meaningful style and use text properties like "userinput" instead of italic. The problem is, of course, that such a program does not appear to exist. Even though it would be perfectly possible to create it (Oce was creating it while I was working there, but it never hit the market). Nevertheless, quite often you just want to make text bold and not worry about how to name that kind of text. Or add a line break without starting a new paragraph (haven't figured out how to do that yet in docbook). Sometimes it's just the layout that matters. > Would you regard Vim's helpfiles as requiring editing in some kind > of special format? I certainly would, but I find the format very > helpful and worthwhile to master, and not that exacting. True, but it's a format that is nearly impossible to convert to HTML or PDF, except by taking the text as-is, without reformatting. And a monospaced font needs to be used, otherwise columns of text are messed up. > Both StructuredText and reStructuredText look very like plain text, > just with certain conventions, not more complicated than the helpfile > format. Problem with these formats is it's even more difficult to mark pieces of text to be a specific kind. E.g., to specify that certain columns of text are part of a table. Especially something like: item1 this is a wrapped default value line explaining item1 in detail item2 something like that another value > Compare this: > http://docutils.sourceforge.net/spec/pep-0258.html > and this, the reStructuredText source: > http://docutils.sourceforge.net/spec/pep-0258.txt > > Does that txt look like a pain to write to you? Sure, looks quite nice. But what's the point? It's not what works, it's what _not_ works what matters. I don't see a table in this example. Can reStructuredText do nested tables? I need that. I might sound a bit frustrated, it appears too difficult to find good documentation tools that are easy to use. Perhaps it's my next project... > > Using a restricted set of the docbook macros doesn't make it > > much simpler. > > The restricted set of tags does reduce the size of the reference > you need to be familiar with. Hmm, I am currently familiar with a restricted set, but it may grow any moment. Why limit the growth? If you add some new tag it's easy to lookup what it does. It's the other way around that's complicated: wanting to add text in a certain structure and not knowing what tags to use. -- If they don't keep on exercising their lips, he thought, their brains start working. -- Douglas Adams, "The Hitchhiker's Guide to the Galaxy" /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// Creator of Vim - Vi IMproved -- http://www.Vim.org \\\ \\\ Project leader for A-A-P -- http://www.A-A-P.org /// \\\ Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html /// |