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

[julian.reschke at gmx.de (Julian Reschke)]

On 2016-03-01 18:15, Joe Hildebrand (jhildebr) wrote:
> On 2/29/16, 10:57 PM, "Julian Reschke" <julian.reschke at gmx.de> wrote:
>
>
>
>> That sounds like a really complicate plan for fixing something that the
>> existing tools have handled just fine in the past. I'd just stick with
>> the status quo.
>
> The existing tools don't have the requirement for multiple people to write new output formatters in a way that the output text look as similar as possible to one another.

Yes, but somehow they managed to do the right thing anyway.

I totally agree it needs to be stated somewhere, though.

> All of the other sections have section numbers applied by the prep tool.  With the current XML, each output format writer now has to calculate what section number goes on each <references> section.  I'll note that I had to fix 4-5 bugs on that.  Not only was my TOC wrong by default, but it wasn't clear to me that a single <references> section doesn't get a higher-level containing section.  Example:

Right. When something isn't documented, and you do not look at what 
existing implementations do, you may end up doing something other than 
the existing tools do.

So yes, it needs to be documented.

> ```
> <references><name>My References</name></references>
> ```
>
> Generates:
>
> ```
> 4. My References
> ```
>
>
> Whereas:
> <references><name>Normative References</name></references>
> <references><name>Informational References</name></references>
>
>
> ```
> 4. References
> 4.1 Normative References
> 4.2 Informational References
> ```
>
> I get that you think that getting these numbers right is trivial, but we've added part numbers everywhere else that we would need to do this calculation, *precisely* for this reason.

Right now I'm concerned about authoring and formatters, not the preptool.

If I understand your proposal correctly you propose that the old format 
continues to be ok, but there'll be another way of doing things, that'll 
be output by the preptool, and that any formatter will have to 
understand. That makes things worse (IMHO), because there are now *two* 
ways to achieve the same thing -- you can't fix a complexity problem by 
adding more complexity.


Best regards, Julian