[rfc-i] draft-iab-html-rfc-02: references

[jhildebr at cisco.com (Joe Hildebrand (jhildebr))]

Even worse, there might be one, two, or more <references> children of <back>.  If there is one, it's the entire References section.  If there are two or more, the output formatter has to create a section to contain all of the <references> sub-sections.

One way to make this less error-prone in the output formatters would be to make these changes:

- v3 would add a new <referencesection> element as a child of <back>, which can occur at most one time.  If there is a <referencesection>, <back> must not include any <references>.  <referencesection> can contain one or more <references>, and may have a <name>

- if the <referencesection> does not have a <name>, the prepTool adds one with the text "References"

- referencesection/name gets slugified by the preptool, as all <name> elements do

- if the prepTool sees more than one <references> child of <back>, it creates a new <referencesection> element (if one doesn't exist), and moves the existing <references> children of <back> to instead be children of <referencesection>

- the prepTool would assign part numbers to <referencesection> and <references> starting with the next-highest number from those used in middle/section/@pn, and treating referencesection/references as a sub-section

- if there is only a single <references> child of <back>, it remains unchanged by the preptool, other than getting a @pn

-- 
Joe Hildebrand







On 2/29/16, 1:38 PM, "rfc-interest on behalf of Joe Hildebrand (jhildebr)" <rfc-interest-bounces at rfc-editor.org on behalf of jhildebr at cisco.com> wrote:

><references> also needs to have a @pn attribute.  It doesn't at the moment.  There needs to be a prepTool step to add the @pn's.  Right now, my HTML output formatter is having to guess the section numbers, which is a recipe for different output in different formats.
>
>-- 
>Joe Hildebrand
>
>
>
>
>On 2/29/16, 10:35 AM, "rfc-interest on behalf of Joe Hildebrand (jhildebr)" <rfc-interest-bounces at rfc-editor.org on behalf of jhildebr at cisco.com> wrote:
>
>>In the prototype, I have a couple of bugs around preparing the name of <references>.  What I think should happen is that:
>>
>><references><name>Informational References</name></references>
>>
>>Gets prepared to:
>>
>><references><name slugifiedName='n-informational-references'>Informational References</name></references>
>>
>>
>>Which gets turned into this HTML:
>>
>><section id="n-references">
>>  <h2 id="s-4">
>>    <a class="selfRef" href="#s-4">4.</a>
>>    <a class="selfRef" href="#n-references">References</a>
>>  </h2>
>>  <section id="n-informational-references">
>>    <h3 id="s-4.1">
>>      <a class="selfRef" href="#s-4.1">4.1.</a>
>>      <a class="selfRef" href="#n-informational-references">
>>        Informative References
>>      </a>
>>    </h3>
>>...
>>
>>
>>I think if there's an anchor on <references>, it's supposed to replace "n-informational-references" in the HTML.
>>
>>-- 
>>Joe Hildebrand
>>
>>
>>
>>
>>
>>
>>
>>On 2/27/16, 9:54 AM, "rfc-interest on behalf of Julian Reschke" <rfc-interest-bounces at rfc-editor.org on behalf of julian.reschke at gmx.de> wrote:
>>
>>>On 2016-02-27 17:38, Paul Hoffman wrote:
>>>> ...
>>>>> but it's also not what the tools generate today,
>>>>
>>>> Right: we're talking about new tools for a new vocabulary
>>>>
>>>>> and most likely not what the RFC production center wants.
>>>>
>>>> Neither you or I work for the RPC; we can let them comment on what they
>>>> want.
>>>
>>>Please.
>>>
>>>>>>>> <section id="n-references">
>>>>>>>> <h2 id="s-3">
>>>>>>>> <a href="#s-3" class="selfRef">3.</a>
>>>>>>>> <a href="#n-references" class="selfRef">References</a>
>>>>>>>> </h2>
>>>>>>>> <section id="n-informative-references">
>>>>>>>> <h3 id="s-3.1">
>>>>>>>> <a href="#s-3.1" class="selfRef">3.1.</a>
>>>>>>>> <a href="#n-informative-references" class="selfRef">
>>>>>>>> Informative References</a></h3>
>>>>>>>> <dl class="reference">...
>>>>>>>> </dl>
>>>>>>>> </section>
>>>>>>>> </section>
>>>>>>>
>>>>>>> This doesn't explain where the ID for the enclosing section comes from.
>>>>>>
>>>>>> Which ID are you referring to? Both of those look pretty clear to me,
>>>>>> but maybe I'm missing something.
>>>>>
>>>>> It's not clear where they come from; from the source document? Are
>>>>> they automatically inserted?
>>>>
>>>> They are automatically inserted by the prep tool, as described in
>>>> section B.2.1 of the v3 vocabulary document.
>>>
>>>OK, I missed that, sorry.
>>>
>>>What's not clear then is where the value of an anchor attribute on 
>>><references> would end up.
>>>
>>>Best regards, Julian
>>>
>>>_______________________________________________
>>>rfc-interest mailing list
>>>rfc-interest at rfc-editor.org
>>>https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>>_______________________________________________
>>rfc-interest mailing list
>>rfc-interest at rfc-editor.org
>>https://www.rfc-editor.org/mailman/listinfo/rfc-interest
>_______________________________________________
>rfc-interest mailing list
>rfc-interest at rfc-editor.org
>https://www.rfc-editor.org/mailman/listinfo/rfc-interest