Le 18/04/2014 11:17, Lex Trotman a écrit :
[my_chapter_title]
[[my_chapter_title]] or if you are like me [[mt]] :)
That runs a high risk of collision. :-)
== My chapter title
(...)
For details refer to <<my_chapter_title>>.
I was worried about doing something wrong, but actually it looks like with
this pattern applied there is no problem.
Yep, if an explicit id is specified no automatic one is generated.
I think it's the only sane way to go, if alone for the reason of keeping
reference integrity when the title gets adjusted.
IMHO, auto-generating ids is good *only* for auto-generated links. I'll
explain more below.
> For this reason, ascii-ids should actually become default.
I don't like the idea of making a nasty hack workaround for one broken
toolchain the default, but more importantly it will break all existing
documents that do refer to autogenerated section ids.
There is a nasty hack. But it is not generating id that are ascii or
whatever.
Where is the hack then ?
The asciidoc *syntax reference* does not state the precise id generating
algorithm, with all collision avoidance rules and warnings (_2 suffix,
etc), does it ?
Then this id generating stuff is not part of the *asciidoc interface*
that documents should abide to. It's an *implementation detail* for this
specific asciidoc processing implementation. Worse, this implementation
detail has two variants.
The real nasty hack is having humans write *manual* (therefore fixed)
references to ids that are *generated* depending on a *particular*
implementation.
That is the nasty hack, not the choice of generating ascii or unicode ids.
Remember the difference between interface and implementation. Documents
should obey the asciidoc interface (syntax, etc). The id generation
algorithm is not part of the interface. The generated ids could be
UTF-8, ROT13, MD5, chapter text translated to klingon through an HTTP
call, whatever, even with randomly changing parts between runs, the
document should not rely on that implementation detail and compile in
all cases.
Now that we've realized that manually linking to generated ids is broken
anyway and should not be done, we can think correctly about the real
value of generated ids.
It is okay to use generated ids, in generated links only.
It happens that full unicode ids are not portable, ascii ids are portable.
And by "portable" I mean already with asciidoc implementation, not even
with another implementation like asciidoctor.
So, when using generated ids correctly (that is, in automatic links
only), ascii ids are safer and have no drawback.
To summarize :
* writing manual link to generated ids and hope it will work: nasty hack
-- broken in theory, works in some cases in practice but fragile.
* generating non-ascii ids (whether they are used or not): legit in
theory, in practice breaks even simple documents with some backends.
That's what "non-portable" means.
* generating ascii ids: legit in theory, safe in all practical cases.
Is my point clear about where the nasty hack is and is not ?
For that reason, making an
explicit id ensures identity and is the right thing to do.
Yes, but boring and messy.
Yes : agreed. Boring ? I disagree. Messy ? On the contrary, relying on
generated ids is messy.
It will break existing documents that refer to autogenerated ids.
Having archived documents fail to generate properly is a bad thing :(
Can you name some of those documents, are there some publicly on the
Internet ?
My opinion is: those documents, if they exist, *are* already broken. In
theory they are a nasty hack, in practice they are fragile.
They are broken like a source code that happens to compile on one
compiler and be rejected by a more correct one which rejects ambiguous
or fragile constructs.
Worse, they are broken like a source code that happens to compile on one
compiler and be rejected by the same compiler when a
non-interface-breaking option of the compiler is enabled (that is, an
option where a compliant input will get processed correctly with or
without the option).
Do they work with another asciidoc implementation ? I guess probably not.
Worse is that this asciidoc implementation chokes on perfectly legal
documents when using default latex toolchain. This is, in practice, very
bad for users and a sign that asciidoc interface is good, but leaves
room for other, more compliant, asciidoc implementations.
After the change, in theory some documents that compiled okay would not
compile. That's called a "breaking change". Breaking changes should be
performed only after sanity checks. After validation they are the way to go.
Back to your objection, it is mostly theoretical and defending bad
practice.
When asciidoc implementation is fixed it would be nice to include a
breaking change explanation about those theoretical documents and
instructions on how to fix them.
If people object about the new code citing collections that can't be
fixed, then asciidoc may consider compatibility with broken documents.
For example with a compatibility flag. Users of those documents can
stick to the old release until the flag is available.
In all other situations, the first move (fix the implementation) was the
only effort to do.
To summarize :
* documents manually linking to so changing an fragile generated ids is
bad practice and makes non-portable, fragile documents
* it's a free software world, release early release often, software that
helps people replaces software that is broken.
Thinking about theory is good, but move on and see what the outside
world decides.
Regards,
--
Stéphane Gourichon
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/asciidoc.
For more options, visit https://groups.google.com/d/optout.
