Re: [Docutils-users] why docutils should reject Alan's proposal

[Alan G I. <ai...@am...>]

Paul,

I cannot tell from your post whether you actually
understand how BibTeX's optional text works.  Do you?
Millions of users have found BibTeX pretty darn useful.
I ask yet again, what part of your critique would *not* apply
to BibTeX's handling of optional text?  Can you please
respond to this question? (It provides important
context for the conversation.)

I'm just asking we take a small step by adding functionality
that millions of BibTeX users have proved is useful.

It would be one thing if you were proposing some better
way to move forward, but instead you seem to insist that optional
text not just be arbitrary optional text but come with a grammar.
As I explained multiple times, this is exactly what my
proposal intentionally does not do.

My only proposal is that docutils support optional text
for citation references, instance by instance.
Yes: a single string. You ask "what use is that?"; well,
ask millions of BibTeX users.  It is useful!

Finally, you seem to think I am putting forward an
implementation proposal.  I am putting forward only
a proposal that developers agree in principle to allow
optional text, and find a syntax to support it.
I've proposed one at the document level, one that
is easily parsed and backward compatible.  Here is
another: use the vertical bar.

    [mycite|optional text]_

I am not in any way attached to this.  I have also
urged that docutils treat the optional text as a simple
string and not commit to parsing it in any way, because
otherwise we need agreement on many things whereas
getting agreement even on allowing any extra information
at all will be hard to get.

Note too that you offer an example where the citation
is changed by the optional text.  That is not what
I proposed: the citation is what it is. The optional
text for the citation reference only affects that
particular instance of the citation reference.
(Again, compare with BibTeX.)  E.g., [mycite{p.10}]_
would become e.g. ::

   <citation_reference ids="id1"
   refid="mycite">mycite <crtext>p.10</crtext></citation_reference>

and then [mycite{vol.3,p.10}]_ would become e.g. ::

   <citation_reference ids="i2"
   refid="mycite">mycite <crtext>vol.3,p.10</crtext></citation_reference>

I am not proposing the details! The important thing is that the citation
would be unchanged. Both references would be to the same citation.
That is the only goal: to allow optional text in the citation references,
instance by instance.

Finally, you can have what you would like even if
my wishes are accommodated. For example, suppose there
were agreement to allow optional text as I request,
perhaps using the vertical bar as above.  Then when
you persuade everyone of a useful and meaningful
grammar for additional text, you could introduce
it using braces.  If it is superior -- and honestly
I imagine it will be in every way aside from date
of implementation -- then use of the other syntax
will slowly die out.

Alan