mojavelinux
commented
11 years ago List layout is an area of AsciiDoc I am certainly open to revisiting. As I mentioned in issue #623, which has a similar theme to this one, I feel tension in the syntax when attaching blocks to a list item.
The following statement from the AsciiDoc User Guide, which you cite in this issue, is simply inaccurate.
Lists can be indented. Leading whitespace is not significant.
It's more accurate to say:
Whitespace preceding the list marker on the first line of a list item is not significant.
For the remaining blocks associated with a list item in an outline list, leading whitespace is significant (normal AsciiDoc rules). In definition lists, whitespace the precedes the definition when its on a line below the term is not significant. Again, for the remaining blocks associated with a list item in a definition list, leading whitespace is significant.
With that clarified, I'd like to move on to a possible compromise that works within the core constraints.
The AsciiDoc processors make a deep-rooted assumption that blocks are defined on the left-hand margin. This is about more than just ease of processing and speed. It's an intentional departure from indentation in XML. Fixing indentation is a silent time killer. Taking the option away removes the temptation for a writer to waste time on it.
Thus, allowing blocks to be indented would have a ripple effect through the processor logic and break a lot of existing documents. I'm not saying we will never do it, but I'd like to explore and/or rule out alternatives before we go there. For now, let's work with the constraint that blocks have to be at the left margin.
What makes a list item with complex content hard to read is the lack of a vertical guide to indicate association. Here's how your example looks today in AsciiDoc:
The following types of animals exist:
* Birds
* Mammals
** Land-Mammals
+
Here's how to describe a land-mammal of these in java:
+
[source,java]
----
String s = "Gorilla";
----
+
Subtypes:
*** Apes
+
WARNING: humans are apes.
*** Rodents
** Sea-Mammals
+
NOTE: Sea-mammals breath air, not water
* InsectsOnce your eye leaves "Land-Mammals", it's hard to keep track of the list's depth. What might help is to allow the list continuation character (+) to align with the list marker. Here's how that looks:
The following types of animals exist:
* Birds
* Mammals
** Land-Mammals
+
Here's how to describe a land-mammal of these in java:
+
[source,java]
----
String s = "Gorilla";
----
+
Subtypes:
*** Apes
+
WARNING: humans are apes.
*** Rodents
** Sea-Mammals
+
NOTE: Sea-mammals breath air, not water
* InsectsWith this change, your eye can at least follow the list continuation characters vertically to keep track of where you are.
Leading whitespace in paragraphs is much easier to play with since its already allowed in the syntax. We could recognize the conceptual shift of the left margin and make whitespace equal to that offset insignificant. Here's how that looks:
The following types of animals exist:
* Birds
* Mammals
** Land-Mammals
+
Here's how to describe a land-mammal of these in java:
+
[source,java]
----
String s = "Gorilla";
----
+
Subtypes:
*** Apes
+
WARNING: humans are apes.
*** Rodents
** Sea-Mammals
+
NOTE: Sea-mammals breath air, not water
* InsectsWith the exception of the listing block, that matches your original proposal. When I see this syntax, I don't get an uneasy feeling like I do when I look at the first example in this comment. I think we've come a long way.
wdyt?
lordofthejars
ge0ffrey
peff
ggrossetie
gzagatti
In .java and .xml files indentation (= leading spaces) have 0 effect on the output (xml has 1 unusual exception). In *.md files, they have effect out the output, but the rules do not prevent typical indentation for readability.
The AsciiDoc quick reference states "Lists can be indented. Leading whitespace is not significant.". Unfortunately that's not the case for *.adoc files:
Try indenting a complex, nested list with a nested list with code fragments and extra paragraphs in the listitems. Something like this should do the trick (untested):
In complex lists like these, indentation is crucial for a reader to be able to recognize the structure and avoid getting lost.
PS: trailing spaces should be insignificant too.