gmane.ietf.rfc.interest

Re: Proposed new RFC submission requirements

Joe Hildebrand — 2012-05-26T07:00:23


I was only talking about sections.  There's no good way in HTML to do list
items without an ol or ul around them, and I don't believe that Word is
generating lists without wrappers.  In a text-only format, this is exactly
the sort of ambiguity that the doc doesn't have enough structure to answer.
In the face of a lack of data, I'd say that it's one list with four items.
If it doesn't matter to the author enough to use a tool that preserves his
or her intent, then nobody else is likely to care about the difference
downstream.


If Word is generating <li> without a <ul> or <ol> around it, there's a bug.


English text contains paragraphs.  In RFC's, we often group multiple
paragraphs together into a section; the lineprinter format uses a blank line
to delineate a paragraph boundary.

Word knows how to deal with paragraphs.  It's inserting br's in order to
gain control over line splitting, which is one of the things we're trying to
solve for in the "reflowing" discussion.


If you know the size of the screen

Re: Pagination requirements

Joe Hildebrand — 2012-05-26T06:49:19


Grab all of the text from a section, including the headers, for all
subsections.

It's the subsections part that's harder without containment.

Regardless, we're going back and forth over what is likely the least
interesting part of the discussion.  Let's try to let it drop until we
figure out some of the macro issues.

Re: Proposed new RFC submission requirements

Joe Touch — 2012-05-26T06:40:28

On May 25, 2012, at 11:30 PM, Joe Hildebrand wrote:


Here's the counterexample:

heading
para
para
para
list item
list item
list item
list item

Is that one list of four items? Is it two lists of two items each? Where is the list container? Does the list belong to the paragraph that precedes it, or as a separate container belonging to the heading level?


Some of it is easy - as you note, I can generate tags that contain sections within the headings that delimit them.

I cannot generate section containers for groupings that cannot be indicated by Word - as per the list above. 

Further, why group all the paragraphs under one heading? At least one output from Word treats them as one long paragraph with BRs in between, rather than as individual paragraphs.

That isn't the same structure most people use when writing XML2RFC, but it is just as valid.


But not necessarily the same container.


You've only given the same reason repeatedly - editing. Support for editing was not given for any forma

Re: Pagination requirements

Joe Touch — 2012-05-26T06:34:18

On May 25, 2012, at 11:22 PM, Joe Hildebrand wrote:


You're adding a requirement to the submission format that has not been shown. That requirement limits the author formats, without demonstrated necessity.


Sure, but that alone does not justify the need for containment. Containment is needed for *editing*, not necessarily for generation.


Presentation and navigation need to be able to be generated from the submission format. I assume that means they need to be present in that format.

The same is not true for editing information.


The published document should probably support cut and paste - but there's no reason that needs containment. There's absolutely no motivation for being able to grab text without headers (the only example provided thus far) except as an exercise in oblique editing techniques.

Joe

Re: Proposed new RFC submission requirements

Joe Hildebrand — 2012-05-26T06:30:18


Disagree.  In my whiteboard thinking this afternoon, the algorithm seemed
pretty straightforward.  You hoist each root portion of the doc that
shouldn't be at the root up to be a child of the section with the next lower
number.


You post-process the output of Word anyway.  Whoever writes the
post-processing tool is going to have to write a few lines of code.


I assume the sections are separated by a header, which has a depth
associated with it?  Everything between headers is in the same section.


I've given two.

Ironically, I started out more-or-less agreeing with you, and you've talked
me out of it.

Re: Pagination requirements

Joe Hildebrand — 2012-05-26T06:22:46


Because I asked nicely?  Because we're having a technical discussion, where
implementation complexity is a relevant design parameter?


I reject that claim.  If the Editor is going to generate multiple output
formats from the submission format, the submission format must be easy to
handle programmatically.  As such, presentation and navigation are secondary
issues for the submission format, and are only at relevant in the case where
the submission format is one of the output formats (as would be possible
with HTML).


Oh, you mean that you don't want to be able to retrieve information from the
published document easily.  I think that's short-sighted, particularly if we
can provide the capability with relatively little overhead.

Re: Towards Consensus

Joe Hildebrand — 2012-05-26T06:17:48


Replace "metadata" with "useful metadata", then, which the lineprinter
format does NOT contain.

Re: Proposed new RFC submission requirements

Joe Touch — 2012-05-26T06:16:23

On May 25, 2012, at 11:10 PM, Joe Hildebrand wrote:


Not all author formats keep the containment structure you expect. If they don't, it cannot be extracted to be provided as an input format.

E.g., Word doesn't use that structure. I could add it for heading sections (it's easy to generate from nested navigation tags), but cannot generate it for lists or other sections - there's no way to differentiate between a set of paragraphs that are not related and ones that are, so there's no way to group them in a container.

Again, except for editing, why does this matter? I have not seen a requirement that drives the need for containment labels.

Joe

Re: Pagination requirements

Joe Touch — 2012-05-26T06:13:06

On May 25, 2012, at 11:06 PM, Joe Hildebrand wrote:


Why should I think about that code? Why is that ever needed except to edit?

That is definitely NOT a presentation or navigation issue. It is thus out of scope for as a requirement for the submission format, I claim.


Your need for code is a need to support reuse after it's published in a new doc. I contend that this support for reuse is not - and should not be - a requirement.

Joe

Re: Towards Consensus

Joe Touch — 2012-05-26T06:10:25

On May 25, 2012, at 10:05 AM, Phillip Hallam-Baker wrote:


The question of normative document refers to "which document *is* RFC 5280". Whether anyone follows that doc or not is a separate issue.


The RFC Editor *does* publish RFCs, and those RFCs have an ISBN number. It's absolutely relevant to ask what is being published - and what alternate forms (which are not being published, but are being made available as a convenience) exist.


The production tool doesn't matter. Authors do NOT verify the correctness of the nroff or xml2rfc versions; they verify the *txt* that the RFC Editor provides (and we don't know - or care - how they manage that).

I.e., there could be many variants of nroff or xml2rfc that generate indistinguishable output. None of those differences are relevant, since the RFC Editor never makes its internal versions available to others. It does make the author's version available upon request for some versions.


It does have metadata, but not in a way that's necessarily automatically extr

Re: Proposed new RFC submission requirements

Joe Hildebrand — 2012-05-26T06:10:29


Can you give a couple of reasons why you think this is "impossible"?   It
seems pretty straightforward to me, so maybe you've thought of a problem I
haven't, since I assume that you wouldn't use a word as strong as
"impossible" without a really good reason.

Re: Pagination requirements

Joe Hildebrand — 2012-05-26T06:06:48


I really don't understand why this is so difficult to explain.

Contained:

<div class='section' id='security'>
  <h2>Security Considerations</h2>
  <p>Para 1</p>
  <p>Para 2</p>
  <div class='section'>
    <h3>Subsection</h3>
    <p>Para 3</p>
  </div>
</div>

Flat:

<h2>Security Considerations</h2>
<p>Para 1</p>
<p>Para 2</p>
<h3>Subsection</h3>
<p>Para 3</p>

Think about the code that would be required to pull out "Para 1 Para 2 Para
3".  In the contained version, it's just $("div#security").text(), and
you're done.  In the flat version, you'd need to write a bunch of code that
basically implemented the HTML5 section rules, or turn it into the contained
version first (which might actually be easier).


I really don't understand that statement.  Why would the containment change
over time?  Once the file is published, it's immutable.

Re: Proposed new RFC submission requirements

Joe Touch — 2012-05-26T05:47:58

On May 25, 2012, at 7:51 PM, Phillip Hallam-Baker wrote:


The key issue is "what is the required metadata".

If it's minimal, it should be easy for most author systems to support:
metadata:
- title
- authors
- date
- RFC number
- RFC category and status
internal "jump" points:
- headings
- figure/table/example labels
- references

I'd really like to see what that is beyond the list I've shown here. I can see a good reason for metadata (supports document identification/location) and jump points (supports navigation based on "landmarks").

If it requires denoting the full document structure, that's hard to impossible, and not clear why that would/should be a requirement.

Joe

Re: Proposed new RFC submission requirements

Phillip Hallam-Baker — 2012-05-26T02:51:35

Would it help to distinguish between the authoring format and the
submission format?

I could not give a hoot what the authoring format is that people use.
No really, knock yourself out engraving it into little stone pyramids
if you like.

What is of significance is the submission format(s) and the internal format.


It almost certainly makes best sense for the IETF tools to use a
single format internally even if multiple submission formats are
supported. So that format might be XML2RFC, or HTML or even nroff. All
that matters is that the submission format be machine parseable to
identify the various elements (sections, abstract, boilerplate, etc.)
and that the internal format is not lossy.


So I don't think we should argue over the internal format at all. Let
the tools group decide on that according to what is easiest for them.

I don't think we need argue XML2RFC or HTML as a submission format
either since we can already turn XML2RFC into something very close to
what we want for the other and we need to b

Re: Pagination requirements

Joe Touch — 2012-05-26T02:02:19


On May 25, 2012, at 5:58 PM, Joe Hildebrand <jhildebr< at >cisco.com> wrote:


That's trivial in general using diff and search. It has nothing to do with containment unless containment is retained across reuses - which it likely will not be. 

Joe

Re: Pagination requirements

Joe Hildebrand — 2012-05-26T00:58:11

the submission format for the second, please), I'd like to be able to
extract the security considerations, so I can compare the different
considerations, look for ideas, and track the lineage of text that has been
borrowed for reuse.

That's trivial with containment.

On 5/25/12 4:34 PM, "Joe Touch" <touch< at >isi.edu> wrote:

Re: Proposed new RFC submission requirements

Bjoern Hoehrmann — 2012-05-25T22:49:24

I think I am not okay with that, but the question is not specific enough
to say for sure. For instance, I have found myself to use invalid markup
because some formatting cannot be achieved using valid markup, and I've
used large pre-formatted text sections to work around similar problems.
To illustrate, when someone submits something akin to

  <xml2rfc>
  <plaintext>
  ...
  </plaintext>
  </xml2rfc>

where the "..." is simply a .txt version as you would submit currently,
is that using the xml2rfc format, even though it's not really marked up
in any way? I think you would have largely follow the xml2rfc rules and
features in order to be considered "using" it, and as it is, I think the
xml2rfc format is not up for the task.

Re: Pagination requirements

Joe Touch — 2012-05-25T22:34:52

Paging around in the author source is a role for that format, which may not be the same as the submission format.  

I described a need for tags in the submission format. I have yet to hear a need for section containment - again, in the submission format. 

Joe

On May 25, 2012, at 3:10 PM, Martin Rex <mrex< at >sap.com> wrote:

Re: Pagination requirements

Martin Rex — 2012-05-25T22:10:27

While automatic and fully dynamic section numbering might help
the chaotic creative processes of some authors, it is not a
necessary prerequisite for producing I-Ds or RFCs for everyone.

While it may take slightly more typing when doing major document
restructuring, having explicit section numbers spelled out in the 
source (as is currently necessary with NRoffEdit) can similarily
help in navigation while paging around in the authoring source.

If being extra chaotic causes extra work, one tends to plan ahead
a little more, and at least for some creative minds, that little
extra planning may well pay off (it does for me).

But I'm also no fan of pathologically small sections
(I would not want my specification to look like a powerpoint).

-Martin

Re: Pagination requirements

Joe Hildebrand — 2012-05-25T21:16:48


I don't think that's a useful distinction in this case.  User navigation is
the same in either approach.  I'm just musing aloud about the consequences
to all of the constituents from a choice in one direction or the other.

Again, to your core point, I don't think it matters *too* much which way we
go, this is just a preference on my part, and one reason why.

Re: Pagination requirements

Joe Touch — 2012-05-25T20:52:05


On May 25, 2012, at 12:36 PM, Joe Hildebrand <jhildebr< at >cisco.com> 

You are confusing an editing requirement with a marking requirement needed for user navigation.  

Joe