Difference between revisions of "Docbook Links"
From GnuCash
(→Motivation: http->https, minor changes in highlight) |
(help -> manual; Update ghelp:; …) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | Docbook offers several forms of links: ''link'', ''olink'', ''ulink'', ''xref''. This page will one day explain, which form to use in which case. | + | Docbook offers several forms of links: ''link'', ''olink'', ''ulink'', ''xref'' [http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5LinkExamples Examples]. This page will one day explain, which form to use in which case. |
| + | [[Category:Documentation Development]] | ||
| + | |||
==Motivation== | ==Motivation== | ||
| − | While document internal links are easy, cross references between different documents, here Guide and | + | While document ''internal'' links are easy, '''cross references''' between different documents, here Guide and Manual, are difficult. |
| − | * When we supported only xml for yelp, we used URLs with the | + | * When we supported only xml for yelp, we used URLs with the protocols |
| + | *;<tt>ghelp:</tt>: It searched for | ||
| + | *:<tt>/usr/[locale/]share/gnome/help/<docname>/<LANG>/<docname>.<extension></tt>. | ||
| + | *:;Important:In 2022 Yelp dropped this extension! | ||
| + | *;<tt>help:</tt>: With the [{{URL:XDG}}wiki/Specifications/help-spec/ XDG help-spec] this was introduced, which searches | ||
| + | *:<tt>/usr/[locale/]share/help/<LANG>/<docname>/index.<extension></tt>. | ||
| + | **You can still use that as shorthand under Linux like to test the german manual <syntaxhighlight lang="sh"> | ||
| + | LANG=de_DE-utf8 yelp help:gnucash-manual | ||
| + | </syntaxhighlight> | ||
| + | *:But they do not work under other OSes or other file formats like ''html'', ''chm'', ''pdf'', ''mobi'' or ''epub''. | ||
* One approach to circumvent this issue is the use of <tt>https:</tt> in a published resource at ''gnucash.org''. The downside: you can not read it offline. | * One approach to circumvent this issue is the use of <tt>https:</tt> in a published resource at ''gnucash.org''. The downside: you can not read it offline. | ||
| Line 8: | Line 19: | ||
One easy to understand source is [http://www.sagehill.net/docbookxsl/Olinking.html Chapter 24. Olinking between documents] in [http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide] | One easy to understand source is [http://www.sagehill.net/docbookxsl/Olinking.html Chapter 24. Olinking between documents] in [http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide] | ||
| − | |||
| − | |||
| − | |||
Latest revision as of 13:40, 26 April 2023
Docbook offers several forms of links: link, olink, ulink, xref Examples. This page will one day explain, which form to use in which case.
Motivation
While document internal links are easy, cross references between different documents, here Guide and Manual, are difficult.
- When we supported only xml for yelp, we used URLs with the protocols
- ghelp:
- It searched for
- /usr/[locale/]share/gnome/help/<docname>/<LANG>/<docname>.<extension>.
- Important
- In 2022 Yelp dropped this extension!
- help:
- With the XDG help-spec this was introduced, which searches
- /usr/[locale/]share/help/<LANG>/<docname>/index.<extension>.
- You can still use that as shorthand under Linux like to test the german manual
LANG=de_DE-utf8 yelp help:gnucash-manual
- But they do not work under other OSes or other file formats like html, chm, pdf, mobi or epub.
- One approach to circumvent this issue is the use of https: in a published resource at gnucash.org. The downside: you can not read it offline.
So we will have to use olinks. Because olinks are very powerful, they a complicated, not well documented and their elements changed over the time.
One easy to understand source is Chapter 24. Olinking between documents in DocBook XSL: The Complete Guide
