Subject: [xml2rfc] list/@style='hanging' and @hangIndent

From: Julian Reschke <[email-masked]>
Date: Mon, 27 Jan 2014 17:26:46 +0100

Hi there,

for 
<http://greenbytes.de/tech/webdav/draft-reschke-xml2rfc-latest.html#element.list.attribute.hangIndent>, 
I'm currently trying to figure out what to say about hangIndent.

The tricky thing here is that hangIndent is a formatting hint that is 
very specific to how xml2rfc formats "hanging" lists.

Example:

   12    Test

   123   Test

   12345  Test

With hangIndent, the default depth can be tuned.

Now this kind of list formatting is specific to TXT output. When 
producing HTML, the processors that I'm aware of produce HTML definition 
lists (dl/dt/dd). Those will be displayed differently than in TXT, such as:

   12
         Test

   123
         Test

   12345
         Test

Consequently, xml2rfc has *ignored* hangIndent when producing HTML. 
rfc2629.xslt does unterstand it, and uses it to override the default 
indentation. xml2rfcv2 does something weird (all values != 0 lead to the 
same indentation).

We can document the intended behavior for output that uses "compact 
lists". However, I'm not sure what to say for the HTML case (and similar 
formats).

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Mon, 27 Jan 2014 09:05:45 -0800

> -----Original Message-----
> From: xml2rfc [mailto:[email-masked]] On Behalf Of Julian
> Reschke
> Sent: Monday, January 27, 2014 8:27 AM
> To: [email-masked]
> Subject: [xml2rfc] list/@style='hanging' and @hangIndent
> 
> Hi there,
> 
> for
> <http://greenbytes.de/tech/webdav/draft-reschke-xml2rfc-
> latest.html#element.list.attribute.hangIndent>,
> The tricky thing here is that hangIndent is a formatting hint that is very
> specific to how xml2rfc formats "hanging" lists.
> 
> Example:
> 
>    12    Test
> 
>    123   Test
> 
>    12345  Test
> 
> Now this kind of list formatting is specific to TXT output. When producing
> HTML, the processors that I'm aware of produce HTML definition lists
> (dl/dt/dd). Those will be displayed differently than in TXT, such as:
> 
>    12
>          Test
> 
>    123
>          Test
> 
>    12345
>          Test
> 
same
> indentation).

I would propose that we make these styles distinct and make the txt and html
versions do the same things.  That is have a hang text version and a
dictionary version (as previously proposed).  I would be more than willing
to make the changes to xml2rfc and the dtd today if people would agree it Is
the right thing to do.  (Not that I would expect that response.)

Jim

> 
> Best regards, Julian
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc

---

From: Julian Reschke <[email-masked]>
Date: Mon, 27 Jan 2014 20:02:12 +0100

> the right thing to do.  (Not that I would expect that response.)

The problem here is that there simply isn't an HTML/CSS construct that 
will do the same...

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Mon, 27 Jan 2014 11:53:56 -0800

> From: Julian Reschke [mailto:[email-masked]]
> Sent: Monday, January 27, 2014 11:02 AM
> To: Jim Schaad; [email-masked]
> Subject: Re: [xml2rfc] list/@style='hanging' and @hangIndent
> 
> >> producing HTML, the processors that I'm aware of produce HTML
> >> definition lists (dl/dt/dd). Those will be displayed differently than
in TXT,
> such as:
> >> lists". However, I'm not sure what to say for the HTML case (and
> >> similar formats).
> >
> > I would propose that we make these styles distinct and make the txt
> > and html versions do the same things.  That is have a hang text
> > version and a dictionary version (as previously proposed).  I would be
> > more than willing to make the changes to xml2rfc and the dtd today if
> > people would agree it Is the right thing to do.  (Not that I would
> > expect that response.)
> 
will
> do the same...

I would have thought that

<p style="text-indent: -10em; margin-left:10em">

Would have done this.

Jim

---

From: Julian Reschke <[email-masked]>
Date: Mon, 27 Jan 2014 21:41:54 +0100

On 2014-01-27 20:53, Jim Schaad wrote:
> ...
> ...

Can you provide an example?

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Mon, 27 Jan 2014 15:43:10 -0800

So look at section 3.

> Sent: Monday, January 27, 2014 12:42 PM

---

From: Curtis Villamizar <[email-masked]>
Date: Mon, 27 Jan 2014 20:48:07 -0500

In message <[email-masked]>
 
> lists". However, I'm not sure what to say for the HTML case (and similar 

The old text behavior was to add hangIndent to the current indent so
hangIndent=8 would be:

   12      Test

   123     Test

   12345   Test

If the indent was too small at least two spaces were used.

Rarely is this used with a single line so what you'd typically have
is:

   123     Text ......
           and more text.

If you added <vspace blankLines="0" /> you could get (in both text and
HTML versions):

   123
           Test

   12345
           Test

   123456789
           Test

This was very useful for things like defining terminology where some
terms were long.

If you wanted the text separated from the body, then blankLines="1"
could be used.

It would be nice if the vspace could be eliminated and a formating
hint given to the list.  For example, something like:
 <list style="hanging" hangIndent="8 vspaceLines="0">

Going from 1.x to 2.x hangIndent changed and it seems it is no longer
added to the current indent.

Curtis

---

From: Julian Reschke <[email-masked]>
Date: Tue, 28 Jan 2014 08:17:27 +0100

> So look at section 3.

Awesome. I'll have a look (this is experimental output, right?)

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 28 Jan 2014 08:49:57 +0100

> The old text behavior was to add hangIndent to the current indent so

What exactly do you mean by "add to the current indent"? It *overrides* 
the current indent, no?

> Rarely is this used with a single line so what you'd typically have

Yes.

> This was very useful for things like defining terminology where some

Which is why we want a new list type for this.

> If you wanted the text separated from the body, then blankLines="1"

For v3, I don't expect we'll optimize it for plain text output (which 
means: less control over vertical whitespace).

>   <list style="hanging" hangIndent="8 vspaceLines="0">

Almost. What we should have is more list styles (such as the 
"dictionary" style proposed by Jim), but less formatting overrides.

> added to the current indent.

In TXT or HTML output? The latter is known to be defunct, I believe.

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Tue, 28 Jan 2014 07:27:48 -0800

This is hand-blown output - it was hand coded not machine coded

> Sent: Monday, January 27, 2014 11:17 PM

---

From: "Jim Schaad" <[email-masked]>
Date: Tue, 28 Jan 2014 08:02:53 -0800

same
> indentation).

No this is not what it does for text output.  Html output does totally
ignore it.

For text output if not given it uses a default value.  Otherwise it indents
the paragraph by the given amount from the previous paragraph boundary (thus
it is additive for nested lists).

Jim

---

From: Julian Reschke <[email-masked]>
Date: Tue, 28 Jan 2014 17:14:42 +0100

> No this is not what it does for text output.  Html output does totally

...in xml2rfc.tcl, it ignores it for HTML output. In V2, it seems to be 
broken (all values >= 1 yielding the same result). In rfc2629.xslt, it 
uses the value for indentation.

> it is additive for nested lists).

Agreed (and this seems to be consistent with that I said except that I 
didn't consider nested lists -- but come on, nested lists with "hanging" 
style? that asks for trouble :-)

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Tue, 28 Jan 2014 08:55:17 -0800

> Sent: Tuesday, January 28, 2014 8:15 AM
broken (all
> values >= 1 yielding the same result). In rfc2629.xslt, it uses the value
for
> indentation.

Given that it is not doing hanging lists in HTML, it is not surprising that
the value is ignored.

> 
> > For text output if not given it uses a default value.  Otherwise it
> > indents the paragraph by the given amount from the previous paragraph
> > boundary (thus it is additive for nested lists).
> 
didn't
> consider nested lists -- but come on, nested lists with "hanging"

I hate to disappoint you, but this is a very common way that I have found
for people to deal with describing fields in nested structures.  It is
something that I do quite frequently.

Additionally a nested list does not need to be a hang inside of a hang, it
could be a hang side of a numbered list.  

Jim

---

From: Curtis Villamizar <[email-masked]>
Date: Tue, 28 Jan 2014 13:06:39 -0500

In message <[email-masked]>
 
> What exactly do you mean by "add to the current indent"? It *overrides* 

That is a bug IMHO.  See comment below.  In xml2rfc 1.x it added to
the current indent.  So if the indent was 3, it added to that.  If
lists got nested and the indent was 6 (or more) it added to that.

> means: less control over vertical whitespace).

But please at least leave the option to add the linebreak using
<vspace blankLines="0" /> or some other means.

> "dictionary" style proposed by Jim), but less formatting overrides.

Either way works for me.

> In TXT or HTML output? The latter is known to be defunct, I believe.

In txt.  I had a draft complete WGLC a while back and then ended up
with all sorts of diffs due to this (plus one diff due to a bug in
eref).

> Best regards, Julian

Thanks for your work on this.

Curtis

---

From: Curtis Villamizar <[email-masked]>
Date: Tue, 28 Jan 2014 14:40:09 -0500

In message <[email-masked]>
 
> style? that asks for trouble :-)

Example

   There are many types of FOO

      FOO type 1

          Paragraphs ...

      FOO type 2

         In various flavors ....

	 FOO type 2a

	    ...

	 FOO type 2b

	    And so on ...

      FOO type 3

         etc ...

I don't see where nested lists are out of the question.  It would be
more common to make the inner list a numbered list, but there may be
reasons to nest hanging lists.

Curtis

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Jan 2014 16:41:39 +0100

> So look at section 3.

OK, so this indeed *looks* the way it should.

The problem here is that we have a list in the source, but not in the 
HTML, which makes me a bit sad.

What we *should* generate is a HTML definition list, but it appears 
there is no (implemented) CSS support to get the look & feel we want.

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Thu, 30 Jan 2014 08:12:59 -0800

Yes - but looking right is more important to me.

Jim

> Sent: Thursday, January 30, 2014 7:42 AM
HTML,
> which makes me a bit sad.
> 
> What we *should* generate is a HTML definition list, but it appears there
is
> no (implemented) CSS support to get the look & feel we want.
> 
> Best regards, Julian