Re: [Docutils-develop] docutils.dtd: id vs. ids

[David G. <go...@py...>]

On Thu, Apr 20, 2017 at 2:47 PM, Guenter Milde <mi...@us...> wrote:
> On 12.02.17, David Goodger wrote:
>> On Fri, Feb 3, 2017 at 7:45 AM, Guenter Milde <mi...@us...> wrote:
>> > On 2017-01-29, David Goodger wrote:
>> >> On Tue, Jan 17, 2017 at 4:15 PM, Guenter Milde <mi...@us...> wrote:
>> >>> On 2017-01-16, David Goodger wrote:
>
> ...
>
>> >> Note: an element could have multiple IDs in its "ids" attribute. How
>> >> exactly do these get transformed into multiple "id" attributes? I
>> >> imagine there would have to be elements (like "target") added
>> >> appropriately, one per excess ID.
>
> Actually, as only the ID-transfer from targets in `PropagateTargets`
> creates multiple IDs, there is no need to create additional elements ---
> they are already there.

Sure.

>> Automatically generated IDs are fine to remove. But what if there are
>> multiple manual explicit IDs on a node? Which do we choose to keep? We
>> must keep them all.
>
> We would need to prevent the ID-transfer if there is already a
> non-automatic (or content-based) ID on the next element.
>
>
>> > There are additional benefits:
>> >
>> > +1 Simpler document model.
>> >
>> > +2 Document model matches better the model used for HTML and XML.
>
>> You can only have +1/+0/-0/-1. No +2's.
>
> Where is this laid down?

https://www.python.org/dev/peps/pep-0010/

> Why not allow this
>
> a) as a means to weight the items, or
> b) as a shortcut for
>
>    +1 Document model matches better the model used for XML.
>    +1 Document model matches better the model used for HTML
> ?

That "No +2's" was ¾ ;-). But answering seriously:

Because sometimes we add up the votes, and outside of [-1,+1] would not be fair.

Enthusiasm is fine. But votes outside the range of [-1,+1] are
automatically rounded toward 0.

> ...
>
>> >    -> Better interface to the XML world (XML experts will feel more
>> >    at ease with the docutils XML model, simpler post-processing when
>> >    standard datatypes for ID and REFID can be used).
>> >
>> >    Docutils pushing an IDS datatype would be the tail wagging the dog.
>
>> No, Docutils is the master here. The document model is central to
>> Docutils. It is influenced by HTML and XML standards, but these are
>> only used as dumb output formats.
>
> By restricting Docutils to "dumb" output, we are wasting potential.

I'm not saying we shouldn't use smart features of HTML etc. I'm simply
saying that the features of HTML/XML/etc that we use depend on the
needs of the Docutils format, not the other way around.

The Docutils Doctree format is paramount here. XML is only used as an
expression of the internal Doctree format. If XML can't handle a
Docutils-specific construct, that's XML's problem.

> ...
>
>> >    Only a strong use case merits a deviation from "one ID per object"
>> >    rule established in the XML and HTML world.
>
>> The use case is: the user (document author) wants multiple IDs per
>> object.
> ...
>> Here's a situation: A document is written. Later on, two sections are
>> merged into one. The old IDs (old section titles) are preserved as
>> explicit IDs (targets) so that existing deep hyperlinks still work. So
>> a single section will end up with multiple IDs. We must keep them all.
>
> OK.
>
>> Docutils allows this.
>
> The Docutils document model allows this, but rST syntax does not support
> this directly, only via additional "target" elements.

How is that not direct reST support?

"""
.. _this is target one:
.. _this is target two:

This Is Target Three
====================

And some text.
"""

>> The HTML and XML output must adapt.
>
> HTML is the only output format where manually set targets make sense
> (because its the only format where you can have deep links from the
> outside). To generate valid HTML, we recreate target elements for the
> "excess" IDs in the HTML writer.
> It would be simpler to just keep the target elements for "excess" IDs.

Why try to fix what ain't broke?

But I'm not sure I follow. Examples, please.

By "It would be simpler to just keep the target elements", do you mean
"in the Doctree" (as opposed to "in the HTML")? I don't have any
objection to that, beyond "why bother?".

>> > I see this as a high cost high benefit option, a more concrete
>> > proposal must be established in dialogue.
>
>> The cost is too high, and the benefit is too low.
>
> So I drop this feature request.

OK.

To be clear: I was objecting to the idea of removing the IDS attribute
from the Doctree, thereby removing that functionality. And I objected
to letting the tail wag the dog, when it should be the other way
around.

David Goodger
<http://python.net/~goodger>