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?
--
Grant Edwards grant.b.edwards Yow! I'm into SOFTWARE!
at
gmail.com
--
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.
