Hi Grant
There are two issues here:
1. List syntax
2. List grammatical style
List syntax
-----------
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
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,
but read on...
AsciiDoc does not use horizontal indentation to specify list nesting, any
indention is optional, this is intentional:
1. The use of tab characters in text editors makes document interchange
problematic.
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.
3. If you cut and paste text to another level you have to remember to adjust the
indentation.
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.
The use of long multi-paragraph list items quickly obscures the list's premise
and the point that the list item is making. 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.
Cheers, Stuart
On 08/10/10 08:57, Grant Edwards wrote:
I've been using asciidoc to generate a development manual, and the
HTML output looks great (PDF is OK). But I'm repeatedly stumbling
over the problem of list items that consist of anythin more than just
a single paragraph of text.
* How to write list items that contain multiple paragraphs?
What I want to do is something like what I'm showing here, where a
single item contains multiple paragraphs.
This would seem to be the natural way to represent such a thing:
just put in a blank line and then continue at the same "indentation
level".
* FWIW, this seems especially appropriate to those of us used to
writing in Python. It also "looks right" when you look at the text
sources.
It also works well with emacs view of paragraph formatting and
indentation.
And when you want to include a literal block in an item, you would
expect to do somthing like this:
--------------------------------------------------
Here is a literal block that is still part of the second item
--------------------------------------------------
And since this text also starts at the same indentation, it's still
part of the same item. That item can even contain another nested,
indented list like this:
+ one
--------------------------------------------------
with a literal block inside item "one"
--------------------------------------------------
+ two
still part of "two".
- yet
- another
- nested
- list
and still part of "two".
+ three
And here we've resumed the second item in the outermost list.
* And now we're on the third item in the outermost list.
Indeed, the indentation-based nesting shown above is precisely how it
works with reStructuredText, but the only way I can acheive the
desired output using asccidoc turns the input text file into hash:
* Here is the first itemized item. Lorem ipsum dolor sit amet,
consectetur adipiscing elit. Ut magna nisl, laoreet ut condimentum
sit amet, ornare at turpis. Phasellus tincidunt enim at eros
posuere semper.
+
The second paragraph of the first list item now has to start at indent
zero, which makes the text file hard to read.
+
And the intervening lines has to have pluses on them so that things
like the emacs "fill-paragraph" command don't work.
* And here is the second item in the list.
+
--------------------------------------------------
And here is a literal block that's actually part of the second item.
--------------------------------------------------
+
And we're still in the second item, and we want to add nested a list
now.
- If this second-level list has blank lines or other blocks in it
Then it starts to look even worse.
+
This is still part of the first item in the 2nd-level list
And I can't figure out how to continue the "second item" in the outer
level list at this point. The obvious indentation-based notation
doesn't work.
Am I missing something?
So far, I prefer the HTML output produced by asciidoc over rst2html,
but asciidoc's notation doesn't appear to support putting much of
anything inside a list item.
So far I've been re-writing my existing documentation files to
eliminate the use of lists, but that's getting old.
Is it too late to fix this in asciidoc?
--
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.
