| Re: [asciidoc-lang-dev] Proposing olinks |
|
Hi, all,
I apologize for being late to the conversation. I was without power or heat for 77 hours (I'm not looking for sympathy - lots of people had it worse than I did, since many also had no water). I'm just stating why I was quiet for all this time.
As it happens, that worked out, because we wound up about where I would want to be anyway, emphasizing Dan's point that it's good practice to not get into a "fast and furious" loop in this kind of thread.
The point I want to make, though, is about implementation-dependent features. In my opinion, if a feature depends on an implementation, that implementation either does not adhere to the specification or the specification is broken. I remember olinks from DocBook
(I built a couple large document-production systems on top of DocBook). I always regarded them as a problem, partly because of the implementation-dependent bit.
If a language has a feature, the specification should state how that feature works. It should NOT be up to implementations. I really detest having to adjust a document to work with different tools because they chose to tackle some implementation-dependent feature
in multiple ways.
So, please, let's write a spec that doesn't call for anything to be implementation-dependent.
Thanks
Jay Bryant
Senior Technical Writer, Spring
VMware
From: asciidoc-lang-dev <asciidoc-lang-dev-bounces@xxxxxxxxxxx> on behalf of Dan Allen <dan@xxxxxxxxxxxxxx>
Sent: Friday, February 19, 2021 4:31 AM To: AsciiDoc developer discussions <asciidoc-lang-dev@xxxxxxxxxxx> Subject: Re: [asciidoc-lang-dev] Proposing olinks > as "a cross-reference link to the content AUTHORED in the document foo.adoc", then it suddenly doesn't matter what the output filename(s)
might be. > > There doesn't even need to be an actual file named "foo.adoc" (it could be an entry in a database table), but this is the canonical name of another document it in cross-references. > > Flipping it around to think of it as a cross-reference to the AsciiDoc source document rather than to an output file stands the entire problem on its head and suddenly I'm totally happy with it, file extension and all! > > Dan, is this how you think of xrefs?
That is exactly how I think of xrefs. (See
https://docs.antora.org/antora/2.3/features/#source-to-source-references)
There's one gap in the current assumption that David Jencks discovered while working on Antora (the static documentation site generator for AsciiDoc). He pointed out that we shouldn't look for just the .adoc file extension, but rather any file extension.
That would allow for making an xref to a document that was converted, but not from AsciiDoc. One example is an xref to an HTML file generated from Javadoc. In this case, the xref is not "source to source" as I often describe, but still a reference to a structured
document. It's something I think we need to take under consideration. That aside, if the reference is in an AsciiDoc document, then it should definitely be source to source (so we can control how the reference is constructed in the output document).
Best Regards,
-Dan
-- Dan Allen, Vice President | OpenDevise Inc.
Pronouns: he, him, his
|