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

Julian Reschke julian.reschke at gmx.de
Tue Feb 2 14:17:15 PST 2016


On 2016-02-02 22:41, Paul Hoffman wrote:
> ...
>>>> 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?

It depends on what the formatter does with the indentation information.

In any format other than plain text, it can easily style the actual code 
so that it's clear what's indentation and what's content.

See, for instance: 
<http://greenbytes.de/tech/webdav/rfc7230.html#rfc.section.2.1.p.8>

> ...
>> 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?

No, that argument applies IMHO to any output format.

> ...
>> 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.

For once, we want the source code, once a tool extracts it from the XML 
source, to be valid. Right now, this isn't the case for ABNF at least. 
There's also the case where one puts examples into artwork, and leading 
whitespace might distort the example (such as when line length is relevant).

Best regards, Julian



More information about the rfc-interest mailing list