[rfc-i] draft-iab-xml2rfc-02 - alignment of sourcecode

Paul Kyzivat pkyzivat at alum.mit.edu
Tue Feb 2 14:51:50 PST 2016

On 2/2/16 4:41 PM, Paul Hoffman wrote:
> On 2 Feb 2016, at 10:15, Paul Kyzivat wrote:
>> On 2/2/16 12:18 PM, Paul Hoffman wrote:
>>> On 29 Jan 2016, at 10:46, Paul Kyzivat wrote:
>>>> The "align" attribute has been deprecated for <figure> while not
>>>> deprecated on <artwork>. But if your figure is contained in
>>>> <sourcecode>, what is the alternative? "align" isn't allowed there.
>>>> At a minimum, "align" out to be allowed with <sourcecode>.
>>> From a semantic point of view, why would you want to align source code
>>> other than "left"? What does center- or right-aligned source code mean?
>> How does it work for artwork?
> The entire block of artwork (not the lines) is aligned to the center or
> right.
>> I would want the entire block of source code aligned as a unit,
>> left/center/right.
> You haven't answered why. Artwork is art and comes semantically with
> some baggage. To most people, source code is a different, non-artistic
> beast.

You say that, but generally sourcecode will look wrong if it is left 
justified without indent amidst test that is indented.

Of course needs will vary. It won't work to indent sourcecode in txt 
format if that pushes the line ends too far to the right. And for large 
blocks of code not adding indentation may look better. But that is why 
there are options.

>>>> Also, I think left/center/right aren't sufficient alternatives for
>>>> alignment. At least historically I think these have been measured
>>>> relative the left and right of the *page*, without regard to margins
>>>> or current indent level. I would like to be able to align relative to
>>>> those.
>>> In XML, there is no concept of page margins.
>> This is info for the formatter, which may have a notion of margins.
> Do you want to introduce a notion of margins for formatters? If so, then
> having that in the XML would be reasonable. However, so far, no one has
> spoken up for that notion.

I think I misspoke here. I was thinking that txt format had a 3 space 
margin. But in actually looking at it I realize that it doesn't. The top 
level headers and other stuff outside any section isn't indented, so 
effectively there is no margin.

So I guess just indent control would do it.

>>>> For instance, consider ABNF source code. I would like the actual
>>>> content of the sourcecode to be valid ABNF. That means that the first
>>>> line of each rule must have no leading whitespace. So any indentation
>>>> needs to come from the "align" attribute. Generally I would probably
>>>> want to have the rules start out aligned with the current indent
>>>> level, or maybe a bit more.
>>> It sounds like you want "indent", not "align", but even then, I'm not
>>> clear why. The sourcecode for your ABNF can have spaces at the beginning
>>> of the lines, can't it?
>> If it is given spaces at the beginning of the lines then it ceases to
>> be valid ABNF. (The first line of each rule cannot have leading white
>> space.)
>> Currently people *do* put in white space so that it looks right. But
>> then when the ABNF is extracted, the ABNF tools must themselves be
>> modified away from true compliance with the ABNF syntax, so as to
>> allow leading white space on rules. And that in turn is problematic,
>> since distinguishing which lines start new rules is not well defined.
>> This will be a problem for any sourcecode syntax where leading white
>> space is significant.
> I'm still missing it. In a syntax where leading white space is
> significant, why do you want to have the formatter add indentation?
> Wouldn't that be visually confusing?

If I am reading code embedded in text, and there is some question, then 
as a reader visually I automatically infer an implicit left margin for 
the code. My goal is to provide enough control so that the author can 
make the code look "right" in the context where it is presented.

>>>> So it would be good to have additional possible values for "align" to
>>>> cover this, or another attribute (e.g. "indent" to specify the origin
>>>> to which "align" applies.
>>> For that to work, you would need to specify measurement units such as
>>> "spaces".
>> I'm just raising a general need. I'm not hung up on what the right
>> solution is. Using indent "levels", or working relative to the indent
>> level of the enclosing section might be possibilities. Using an
>> attribute other than "align" would be fine with me.
>> Note that the "solution" of putting leading spaces on the sourcecode
>> in order to match up with the indentation of the surrounding text has
>> similar problems to specifying indentation in "spaces". (It won't be
>> right for all different forms of formatting.)
>> Also, assume you get your figure/sourcecode/artwork all set so it
>> works in your document. Then you restructure your document so it is
>> within a section/list at a different nesting level.  It may not look
>> right - you might need to insert extra "indent" spaces to get it to
>> look right. Better not to need that.
> This sounds like you are mostly thinking of the text output, not the
> HTML and PDF output, yes?

I haven't been looking at HTML or PDF output generated directly by a 
formatter. Only HTMLized txt output. So yes, that is mostly what I am 
thinking of. I will need to see directly generated HTML and PDF before 
having an opinion on how needs might differ.

For instance, perhaps code in those formats ought to be "framed" in some 
way, so it is clear what is part of the code and what is there just for 
document formatting.

For some time my preferred format for reading drafts has been the 
HTMLized format. I'm hoping if we move to HTML directly generated from 
the XML that it will be similarly close to how the txt format looks. I 
can see eventually moving away from that, but not as long as there is 
significant use of the txt format.

>>>> Note that all these things also are relevant to line art. But with
>>>> line art there is less reason not to deal with it by including left
>>>> whitespace within the artwork.
>>> Line art is entered in the XML in <artwork>. Are you asking for an
>>> "indent" attribute there?
>> It is of lower priority to me, but I think a solution for sourcecode
>> would be equally applicable to "line" art. It *might* also be relevant
>> for SVG artwork.
> As you can see from above, I'm still unclear on why indenting sourcecode
> that has leading-whitespace rules would help.

Just look at almost any rfc that contains ABNF. Almost all of them have 
been indented, at the expense of ceasing to be valid ABNF. I would just 
like to get the same effect while allowing the ABNF in the xml to be 
valid ABNF.

That way we can have tools to automatically validate XML in drafts 
without having to hack the validators to accept invalid syntax.


More information about the rfc-interest mailing list