Subject: [xml2rfc] Comments and Text for draft-reschke-xml2rfc-03

From: "Jim Schaad" <[email-masked]>
Date: Tue, 7 Jan 2014 21:43:39 -0800

I am going to mail this off because I don't seem to be doing it very fast.
I don't know if you want more detail or less detail on than what is in this
message.

Jim

Section 2.5 - The 'alt', 'height', 'width', 'file', 'type', 'src' and
'xml:space' attributes are currently not used when generating documents.'

Section 2.6 - From what I can tell from the code, it is expected that while
the author name can be absent in a reference, the name attributes are
expected to be present for the author elements that appear in the front
element.  They will default to empty strings, but the empty strings will
then be emitted in the either the header or author sections.

Section 2.6.2 - The current code allows for the separator to be either
whitespace or a dot (or any combination of).

	Unclear if it should be noted that the initials attribute is only
used if a surname attribute is also present.  The current code is
inconsistent on this statement.  It is true for references, but is not true
for the header.

Section 2.6.4 - Should add the text "Authors Surname (used on the front page
and in references)."

Section 2.8 - I am not sure that this is the correct location for this to
appear, however it needs to appear someplace.

The number of columns in the table is determined by the number of ttcol
elements.  The number of rows in the table is determined by the number of c
elements divided by the number of ttcol elements.  There is no requirement
that the number of c elements be evenly divisible by the number of ttcol
elements.

Section 2.13 - When matching the month, the abbreviated version of the month
may be used as well as the full month.

Section 2.13 - Currently in the second case, the day attribute is ignored
when creating a reference.

Section 2.15 - The text states that the URI of the target is enclosed in
angle brackets.  This is not true in the current system.

Section 2.17 - height and width would only duplicate the functionality of
these attributes on the artwork if there is not a preamble or postamble
present.  If these are present, then the height and width would include
these as well, which the one on the figure would not.

Section 2.17 - Currently the alt, height, src and width attributes are
ignored.

Section 2.18 - This element is ignored by the current code.

Section 2.20.2 - This attribute is ignored by the current code

Section 2.22.1 -
 When the style format is used, it is possible to use a single counter
across multiple list element by naming the counter to be used.  If the
attribute is absent, a unique counter is synthetized.

Section 2.22.2 - hangIndent

<t>This attributes allows for a specific indentation level to be specified
for both the 'hanging' and 'format' styles.  The value is the number of
characters to indent the list paragraphs.</t>

Section 2.22.3 - style

<t>The style attribute controls how the elements in the list are going to be
numbered.  If a list does not have  style attribute, then the style for the
current list is inherited from its parent.  If a list has no parent then the
style 'empty' is used.</t>
<t>The style attributes are:
<list style="hanging">
<t hangText="symbols"> uses a set of symbols to tag each paragraph.  The set
of symbols is controlled by the PI text-list-symbols and defaults to 'o*+-'.
There is currently no way to change the set of symbols to be used between
different lists.</t>
<t hangText="numbers"> uses digits to tag each paragraph</>
<t hangText="letters"> uses upper and lower case letters to tag each
paragraph.  Upper case letters are used if the depth of the list is even and
lower case letters are used if the depth is odd.  The depth computation does
not take into account the style attribute.</t>
<t hangText="hanging"> allows for arbitrary text to be used to tag each
paragraph.  If the hangIndent attribute is not specified, then the value of
3 will be used for indentation. </t>
<t hangText="format"> allows for characters to be used for tagging each
paragraph along with additional decoration.  The style attribute is the
string 'format ' followed by text containing one of '%c', '%C', '%d', '%i',
'%I', '%o', '%x', '%X'.  If the hangIndent attribute is not specified, then
the value of 3 will be used for indentation.</t>
<t hangText="empty"> uses not character to tag each paragraph.</t>
</list>
</t>
<t>While this is the list of recognized styles, there does not appear to be
any enforcement of the list of styles in either the dtd or XML2RFC.  Unknown
style strings will be treated as 'empty'.
</t>

---

From: Julian Reschke <[email-masked]>
Date: Wed, 08 Jan 2014 12:45:54 +0100

> I don't know if you want more detail or less detail on than what is in this

Thanks a lot!

> 'xml:space' attributes are currently not used when generating documents.'

They are used by xml2rfc.tcl and rfc2629.xslt. If v2 doesn't use them 
then that is a bug that should be fixed.

(xml:space is special in that it's a signal to the XML processor)

> then be emitted in the either the header or author sections.

This absolutely needs a test case, and also we need to clarify with the 
RSE whether that's a legal use case for an RFC.

> whitespace or a dot (or any combination of).

Is there a reason why we need to support more than one format?

> inconsistent on this statement.  It is true for references, but is not true

That sounds like an xml2rfcv2 problem, no?

> Section 2.6.4 - Should add the text "Authors Surname (used on the front page

Or maybe "used when the 'full name' is not".

> that the number of c elements be evenly divisible by the number of ttcol

Thanks, added.

> may be used as well as the full month.

In xml2rfcv2. I'd prefer we have exactly one format.

> when creating a reference.

True, but will this always be true?

> angle brackets.  This is not true in the current system.

It is true for xml2rfc.tcl when producing plain text, and for rfc2629.xslt.

xml2rfc.tcl doesn't include the brackets in HTML, but I consider this a 
bug because it means that the text content does not match the text version.

For v3 we may want to discuss how far the text content may vary between 
output formats.

> these as well, which the one on the figure would not.

Can you explain how "height" would affect preamble and postamble?

> Section 2.17 - Currently the alt, height, src and width attributes are

In xml2rfcv2 and rfc2629.xslt, but not in xml2rfc.tcl.

> Section 2.18 - This element is ignored by the current code.

In xml2rfcv2 and rfc2629.xslt, that's why I want to get rid of it.

> Section 2.20.2 - This attribute is ignored by the current code

In xml2rfcv2? That's a bug.

> style strings will be treated as 'empty'.

Will get to these soonish. Thanks for the text!

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Wed, 8 Jan 2014 10:45:59 -0800

> -----Original Message-----

> From: Julian Reschke [mailto:[email-masked]]

> Sent: Wednesday, January 08, 2014 3:46 AM

> To: Jim Schaad; 'xml2rfc'

> Subject: Re: Comments and Text for draft-reschke-xml2rfc-03

> > I don't know if you want more detail or less detail on than what is in

> > this message.

> They are used by xml2rfc.tcl and rfc2629.xslt. If v2 doesn't use them then
that

> is a bug that should be fixed.

> (xml:space is special in that it's a signal to the XML processor)

I will have to do a test case to try and figure out if xml:space is
understood and kept by the system.  I was looking for it in the code and did
not consider it being somehow kept by the parser itself.

Given that this document is targeted at the v2 grammar, I am ignoring
behavior of the tcl code because it is v1 grammar.  I am also assuming that
you understand the rfc2629.xslt rules and therefore I don't need to worry
about what piece of code would or would not do.

> > Section 2.6 - From what I can tell from the code, it is expected that

> > while the author name can be absent in a reference, the name

> > attributes are expected to be present for the author elements that

> > appear in the front element.  They will default to empty strings, but

> > the empty strings will then be emitted in the either the header or
author

> sections.

> This absolutely needs a test case, and also we need to clarify with the
RSE

> whether that's a legal use case for an RFC

> > inconsistent on this statement.  It is true for references, but is not

> > true for the header.

> That sounds like an xml2rfcv2 problem, no?

I don't think of initials as requiring a period necessarily.  I would easily
write J L Schaad as my name as J. L. Schaad so that for me initials="J L" is
a reasonable alternative.

> > Section 2.6.4 - Should add the text "Authors Surname (used on the

> > front page and in references)."

> Or maybe "used when the 'full name' is not".

That does not help me from a documentation point of view if I don't know
where the full name is going to be the used version.  It can say you use a
unless you use b.  And you use b in the following cases.  However without
the second qualification the first is not completely useful.

> > Section 2.8 - I am not sure that this is the correct location for this

> > to appear, however it needs to appear someplace.

> > The number of columns in the table is determined by the number of

> > ttcol elements.  The number of rows in the table is determined by the

> > number of c elements divided by the number of ttcol elements.  There

> > is no requirement that the number of c elements be evenly divisible by

> > the number of ttcol elements.

> > Section 2.13 - When matching the month, the abbreviated version of the

> > month may be used as well as the full month.

> In xml2rfcv2. I'd prefer we have exactly one format.

V2 has both formats.  You can have this argument in v3.

> > Section 2.13 - Currently in the second case, the day attribute is

> > ignored when creating a reference.

> True, but will this always be true?

Unless we change v2 - then yes it is aways true.   You can have a discussion
on this for v3.

> > Section 2.15 - The text states that the URI of the target is enclosed

> > in angle brackets.  This is not true in the current system.

> xml2rfc.tcl doesn't include the brackets in HTML, but I consider this a
bug

> because it means that the text content does not match the text version.

> output formats.

For the XML2RFC v2 system, we are consistent - we don't put the angle
brackets in for either the html or the text version.

> > Section 2.17 - height and width would only duplicate the functionality

> > of these attributes on the artwork if there is not a preamble or

> > postamble present.  If these are present, then the height and width

> > would include these as well, which the one on the figure would not.

> Can you explain how "height" would affect preamble and postamble?

Where this starts having real effects if you start doing flowing of text
around the picture.   In the above picture there are two blocks that are
sized - the figure and the artwork.  Each has the possibility of having a
size set to it that controls how much real estate it will be allowed to
occupy.  Normally if one were to specify a width for the figure then the
preamble, postamble and title would be restricted in width to that of the
figure - something that is easier to do in HTML than it is in a text
version.

One of the things that frequently happens is to allow for outside text to
flow around the figure.  This means that specifying the width on the figure
itself becomes important. 

> In xml2rfcv2 and rfc2629.xslt, that's why I want to get rid of it.

I will note that this field is populated in the current reference files that
we get from bibxml

> In xml2rfcv2? That's a bug.

What is the correct behavior for a text based document?  What is the correct
behavior for an html based document?  I don't know what this is supposed to
do so there is no way for me to correctly file a bug on it.  On the other
hand I have never had a need for iref in any document that I have ever
written so I would be willing to kill in this is v3

> >   When the style format is used, it is possible to use a single

> > counter across multiple list element by naming the counter to be used.

> > If the attribute is absent, a unique counter is synthetized.

> > <t>This attributes allows for a specific indentation level to be

> > specified for both the 'hanging' and 'format' styles.  The value is

> > the number of characters to indent the list paragraphs.</t>

> > <t>The style attribute controls how the elements in the list are going

> > to be numbered.  If a list does not have  style attribute, then the

> > style for the current list is inherited from its parent.  If a list

> > has no parent then the style 'empty' is used.</t> <t>The style

> > attributes are:

> > <t hangText="symbols"> uses a set of symbols to tag each paragraph.

> > The set of symbols is controlled by the PI text-list-symbols and
defaults to

> 'o*+-'.

> > There is currently no way to change the set of symbols to be used

> > between different lists.</t> <t hangText="numbers"> uses digits to tag

> > each paragraph</> <t hangText="letters"> uses upper and lower case

> > letters to tag each paragraph.  Upper case letters are used if the

> > depth of the list is even and lower case letters are used if the depth

> > is odd.  The depth computation does not take into account the style

> > attribute.</t> <t hangText="hanging"> allows for arbitrary text to be

> > used to tag each paragraph.  If the hangIndent attribute is not

> > specified, then the value of

> > <t hangText="format"> allows for characters to be used for tagging

> > each paragraph along with additional decoration.  The style attribute

> > is the string 'format ' followed by text containing one of '%c', '%C',

> > '%d', '%i', '%I', '%o', '%x', '%X'.  If the hangIndent attribute is

> > not specified, then the value of 3 will be used for indentation.</t>

> > </list> </t> <t>While this is the list of recognized styles, there

> > does not appear to be any enforcement of the list of styles in either

> > the dtd or XML2RFC.  Unknown style strings will be treated as 'empty'.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 08 Jan 2014 20:19:24 +0100

On 2014-01-08 19:45, Jim Schaad wrote:
> ...
> then that
> understood and kept by the system.  I was looking for it in the code and
> did not consider it being somehow kept by the parser itself.

If xml:space is not "preserve", a processor might remove whitespace.

> behavior of the tcl code because it is v1 grammar.  I am also assuming

The TCL code implements the v2 grammar.

> I don't think of initials as requiring a period necessarily.  I would
> easily write J L Schaad as my name as J. L. Schaad so that for me
> initials="J L" is a reasonable alternative.

Adding micro-formats just makes implementations harder. Why can't we 
standardize on a single syntax?

> where the full name is going to be the used version.  It can say you use
> a unless you use b.  And you use b in the following cases.  However
> without the second qualification the first is not completely useful.

This is a document that describes the vocabulary. It's not supposed to 
fully describe what various processors do with it.

> V2 has both formats.  You can have this argument in v3.

The TCL version even has more formats, because AFAIK it just uses the 
TCL date parser. That doesn't make all of these formats valid.

I'd like to have a single variant. The date format already is overly 
complex (it shouldn't have used english month names in the first place), 
let's not make it worse.

> Unless we change v2 - then yes it is aways true.   You can have a
> discussion on this for v3.

I think you are conflating vocabularies, implementations, and target 
formats.

What we can say is that when used in references, the day is not used 
when formatting as ID or RFC.

>  > xml2rfc.tcl doesn't include the brackets in HTML, but I consider this
> a bug
>

Well, that's a change from the TCL version. I would consider this a bug.

> around the picture.   In the above picture there are two blocks that are

But we don't do that.

> sized – the figure and the artwork.  Each has the possibility of having
> a size set to it that controls how much real estate it will be allowed
> to occupy.  Normally if one were to specify a width for the figure then
> the preamble, postamble and title would be restricted in width to that
> of the figure – something that is easier to do in HTML than it is in a
> text version.
>
> One of the things that frequently happens is to allow for outside text
> to flow around the figure.  This means that specifying the width on the
> figure itself becomes important.
> ...
> I will note that this field is populated in the current reference files
> that we get from bibxml

Yes.

> What is the correct behavior for a text based document?  What is the
> correct behavior for an html based document?  I don’t know what this is
> supposed to do so there is no way for me to correctly file a bug on it.
> On the other hand I have never had a need for iref in any document that
> I have ever written so I would be willing to kill in this is v3

In HTML, the obvious thing is to make the output stand out, such as by 
making it bold.

> ...

Best regards, Julian