On 2010-10-07, Stuart Rackham <[email protected]> wrote: > AsciiDoc places no restrictions on the number of block elements you > can put in a list item -- use list continuation to append block > elements to a list item. You can group multiple block elements in a > single OpenBlock. See: > > http://www.methods.co.nz/asciidoc/userguide.html#X15
I think we can safely assume I knew that since I both included examples of it in my posting and explained about how the "+" was required in asciidoc for multi-paragraph list items. ;) The "+" is a bit ugly, but the main problem I have with the continuaion is that after the "+" line you must unindent. Indentation is not optional at that point in the list item: it's forbidden. In some places in a list, indentation is allowed, in other places it's not. I like the indentation in my source to reflect the structure of the document. Asciidoc doesn't allow that in some places. > Your HTML and PDF outputs are will still be indented -- lack of > indentation in the AsciiDoc source does not imply lack of indentation > in output formats. Admittedly list continuation is not as easy on > the eye until you get used to it, That's my main problem. The structure of the document isn't reflected visually by the input. I think source files should be easily readable by humans -- even ones who don't know asciidoc. > but read on... > > AsciiDoc does not use horizontal indentation to specify list nesting, > any indention is optional, Indentation is _sometimes_ optional. > this is intentional: > > 1. The use of tab characters in text editors makes document > interchange problematic. Yes, I agree. Tabs are evil, and should not be allowed at all in input. > 2. Maintaining correct indentation when entering text is fiddly, it > slows you up and breaks your train of thought, especially if you > don't want or care about indentation. Two points: * I use a text-editor on a computer to write my source files. It knows how to handle indentation in an intuitive manner. I don't have to think about it or do anything to maintain indentation. I just type. I actually have to "fiddle" with it to force it to misalign stuff when writing an asciidoc list item continuation. I sort of assumed that others who write a lot of documents used text editors. * It's important to me that source files be human-readable to a lay-person. To people, indentation is significant. That's why we use indentation in things like C source code. Forcing people to ignore indentation places a higher cognitive load on the reader than need be. > 3. If you cut and paste text to another level you have to remember to > adjust the indentation. True. But, indent/unindent is one keystroke. Most importantly, it's visually obvious when looking at the source file when it's wrong. My philosophy is that source code readabilty trumps a keystroke saved during writing. Source files are only written once or twice, but they are read thousands and thousands of times. > List Grammatical Style > ---------------------- > List items should rarely contain more that a single short paragraph > or phrase. The purpose of a list is to enumerate a premise with a > number points, one point per list item. Ah. I had presumed that asciidoc was about mechanism, not policy. Too many years of using X I guess. > The use of long multi-paragraph list items quickly obscures the > list's premise and the point that the list item is making. You must write different sorts of documents that I do. For example, I write documents explaining how do accomplish certain tasks on a computer. I find that an enumerated list is a natrual way to present the steps involved. So, often I want an enumerated list item to consist of an explanatory sentence or two and a command-line example. I've not been able to figure out how to do that in a readable manner using asciidoc. I think it's import to indent lists so that it's easy for the reader (of the source file) to visually see where each item begins/ends, and how the lists are nested. > If you find your document contains multi-paragraph lists you should > consider making each paragraph a separate point or putting list items > in separately titled subsections. I guess asciidoc is trying to enforce certain writing/editorial policies that under some circumstances I don't agree with. Presumably I should work on fixing up reStructuredTexts CSS files to make the output look better instead of complaining about what I perceive as the readability issues in asciidoc source files. Thanks for explaining the reasons behind things. -- Grant -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
