[
https://issues.apache.org/jira/browse/CAMEL-12417?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16426709#comment-16426709
]
Fintan Bolton commented on CAMEL-12417:
---------------------------------------
Hi [~sekaijin],
I'd like to understand why you want to change the link format from
{{<<TargetID,Text of Link>>}} back to {{link:file.adoc[Text of Link]}}. This
would reverse a lot of the changes I made in CAMEL-12246, where I introduced
the angle-bracket cross reference format [1] into the Camel docs.
As I understand it, the angle-bracket format offers several advantages:
* Because the angle-bracket cross reference does not reference a file name,
you are free to rename {{.adoc}} files and move them around without breaking
the link.
* If you specify {{<<TargetID>>}} without the link text, AsciiDoc can
automatically substitute the text at the target location for you (e.g. title or
section heading).
* Most important of all, the angle-bracket format is compatible with every
kind of documentation build chain. But this is not true of the
{{link:filename.adoc[Text]}} format. If you use the
{{link:filename.adoc[Text]}} format, there is an implicit assumption that the
generated output format is paged HTML, organized with exactly the same
directory structure as the AsciiDoc source. This might work when you generate
paged HTML with the {{asciidoctor}} Maven plugin, but almost any other approach
to building the docs is liable to fail. For example, there is no way the
{{link:filename.adoc[Text]}} format would work for PDF or ePub output.
[1] [https://asciidoctor.org/docs/user-manual/#internal-cross-references]
> Camel documentation
> -------------------
>
> Key: CAMEL-12417
> URL: https://issues.apache.org/jira/browse/CAMEL-12417
> Project: Camel
> Issue Type: Improvement
> Affects Versions: 2.21.0
> Reporter: Terrien Jean-Yves
> Priority: Major
>
> I am rewriting the doc to fit github.
> [https://github.com/jyterrien/camel/blob/master/readme.adoc]
> I replaced .md files with .adoc
> I started correcting the links in readme.adoc contributing.adoc
> and in camel-core. (in alphabetic order from bean-component to file-component)
> I did not find, on github, docs like
> https://camel.apache.org/data-format.html
> [https://camel.apache.org/enterprise-integration-patterns.html]
>
> in every page I've changed the definition
> = title page
> I'e added
> :toc: left
> and I corrected the links <<doc,DOC>> link:doc.adoc[Doc]
> I also when I found the target corrected the relative links like :
> === See Also
> * link:file-language.adoc[File Language]
> * link:../../../../components/camel-ftp/src/main/docs/ftp-component.adoc[FTP]
> * Polling Consumer
> as soon as I corrected all camel-core I think to make a pull-request
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
