Re: [asciidoc-lang-dev] Proposing olinks

[Dave Gauer <dave@xxxxxxxxxxxxx>]

On 2/18/21 2:01 PM, Sylvain Leroux wrote:
> Dave, David, thank you for this interesting discussion.
> 
> On 18/02/2021 19:20, Dave Gauer wrote:
>> The idea of a "Document Set" as a body of AsciiDoc documents makes a
>> clear distinction between links inside the set and links outside the set:
>
> Can't the same document be _part or a set_ with one processor, but
> _outside_ of that set with another processor?


Maybe?

You could have all sorts of combinations like a set of AsciiDoc
documents which produce a website with a printable PDF cheat-sheet:

index.adoc      --> index.html
topic1.adoc     --> topic1.html
topic2.adoc     --> topic2.html
cheatsheet.adoc --> cheatsheet.pdf

Would a link from topic1.adoc/.html to cheatsheet.adoc/.pdf be an "xref"
or a "link"?

What if you re-export the whole thing as one big PDF with all pages and
the cheatsheet included in the same file? It seems like that link from
topic1 to cheatsheet is definitely an "xref" now.

But maybe this example is too specialized to worry about yet.


> This is purely speculative, but I can imagine a 1-1 mapping when
> converting AsciiDoc files to web pages, but the same sources documents
> ending in one or two large PDF when transforming it for print. Or is
> this a total non-sense?


Yes, that makes complete sense!

The 1:1 mapping problem has also bothered me because the output of a
book (EPUB, PDF) vs. website (directory of HTML) are likely totally
different things and in these scenarios, needing to link to "documents"
or "sections in documents" in that output is just...WRONG.


Or take the GNU documentation for example. Here's the exact same manual
exported four different ways:

1. One big HTML page
2. One page per chapter
3. One page per section
4. One page per "node"

https://www.gnu.org/software/tar/manual/tar.html
https://www.gnu.org/software/tar/manual/html_chapter/index.html
https://www.gnu.org/software/tar/manual/html_section/index.html
https://www.gnu.org/software/tar/manual/html_node/index.html

They also have other formats like PDF. Here's the whole list:

https://www.gnu.org/software/tar/manual/

I took at a look at the Texinfo source of that manual and it's using an
"xref" to link to other nodes.

    @xref{<node name>}

Okay, so that's neat, but these GNU manuals are all produced as one big
document, right?  They just happen to have the ability to be OUTPUT as
separate HTML files. No big deal.

True, but it turns out Texinfo totally DOES HAVE the concept of a
cross-references to other manuals.  Check it out:

    "Ordinarily, you must always name a node in a cross-reference.
However, it’s not unusual to want to refer to another manual as a whole,
rather than a particular section within it. In this case, giving any
section name is an unnecessary distraction."

http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Cross-References

(I'm afraid the above URL is going to wrap in this email because the
anchor has a hyphen, so you may need to find "Cross-References" in the
table of contents.)

It goes on to give an example (which is basically a somewhat
clumsy-looking work-around) to point to the "Top" of a document by name:

    @xref{Top,,, make, The GNU Make Manual}.

Where "make" is the name of the document and "The GNU Make Manual" is
the label. "Top" is an implicit node that does not have to be defined by
the author in the linked document.

Texinfo is historically interesting.

-Dave