asciidoc: is there a way to create an anchor that

2019-07-08 05:21发布

问题:

Tl;dr;

What is the correct way to create an anchor in docbook? and is there a way that will make the anchor visible in writer?

Background

I am trying to split up documentation that was previously in single open office documents into smaller asciidoc documents which are both included in the main open office document and also converted to either or both of html & pdf. I have this mostly working. I use asciidoctor to create html. asciidoctor-pdf to create pdf and a combination of asciidoctor and pandoc to create .odt files. I also tried the python implementation of asciidoc but found the interface less useable.

Round tripping between asciidoc and odt is obviously not possible. This is sort of a fusion where the master document is word processed but pieces of content that can be produced independently (think man pages - in fact that is one of several use cases) are included.

asciidoc to html:

asciidoctor -b html5 foo.adoc -o foo.html

asciidoc to pdf:

asciidoctor-pdf -b pdf foo.adoc -o foo.pdf

asciidoc to odt

asciidoctor -b docbook foo.adoc -o foo.docbook pandoc --base-header-level=3 -V date:"" -V title:"" -f docbook foo.docbook -o foo.odt

With pandoc I have to nullify the date and title and set the header-level as desired for the section to be inserted as an extra complication.

I insert the resulting .odt into the main document using insert section inside open office. Note that the main document is not a master document as I could not find a way of creating a master document without also automatically splitting the file on h1 boundaries.

I have two main problems to resolve with this set-up. I would like to add headings in the asciidoc document as cross references and also create entries for them in the alphabetical index (actually the first heading would be suffcient). Is there a way to do this? Index markers in asciidoc do not result in entries in .odt file being created.

I am able to cross reference content in the inserted section using "insert reference/heading" and referencing the uniquely named header. However, whenever I use "update all" these cross references are invalidated. They are shown as "Error: Reference source not found".

[On a separate note I would also like a way to find broken cross references automatically]

I am currently using libreoffice - Version: 4.3.7.2

I am not adverse to switching version or flavours (i.e. apache) if one behaves better than the other.

I'm not sure if the answer is in the asciidoc or docbook parts of the chain. I would accept an answer which inserts a index entry at the start of the inserted section (top of the .adoc/docbook file) automatically.

I am also open to changing my toolchain to something that will work. For example I tried the asciidoc-odt backend and fell foul of https://github.com/dagwieers/asciidoc-odf/issues/47 which does not inspire confidence. Using asciidoc-odt I avoid the need to create an intermediate docbook file. However, I still can't get the anchor to appear.

I can get a macro to create an anchor but at present I haven't figured out how to run the macro from the command line.

回答1:

To create an anchor in DocBook, make an inline anchor in the .adoc file. For example, giving this to asciidoctor:

[[X1]]Section1
---------------

produced this:

<title>
    <anchor xml:id="X1" xreflabel="[X1]"/>
    Section1
</title>

Conversely, putting this on separate lines did not create an anchor tag in my test:

[[X1]]
Section 1

Now for some bad news. From the Pandoc User's Guide:

Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.

I interpret this to mean that currently, Pandoc does not create internal links in Writer. When I tried it, the link was ignored.

Note: It looks like I did not answer all of your questions. If you want to ask more about LibreOffice cross references and headings (the big bold paragraph towards the end of the question), maybe you could make a separate question just for that part.