The reason or intention for page breaks is: You want to present a closed content on two pages side by side.> Whereas in book view mode or for the printed document the left page has the even number and the right page has the odd one.> This is important.> Normally pdf viewer should be able to set for this mode.>

This means also, a new chapter should start on top of an even page to have two pages side by side for the overview.> But in opposite of this rule, it is often recommended to start a new main chapter on right side in a book, the same side as the title was written.> This is a little bit contradictory.> Never you should start an important new chapter near the end of the right (odd) page, that is stupid.> Means, insert manually a page break before.>

Using page breaks on proper positions in the text helps also that the page disposition is not sensitive to confuse on each small text changes.> You have some space before page breaks.>

Traditionally it seems to be proper to insert manually a page break with Menu “Insert {fmin} Page break” or “Insert {fmin} More Breaks”, and then select “Column break”.> But effectively, the property of breaking the page is a property of the paragraph format.> It means following the idea of direct formatting, to to the “Format {fmin} Paragraph”, then select the tab “Text flow”, then check the “Insert” box with Type: “Page” or “Column” and use Position: “Before”, that is proper.> Then you get a column or page break before this paragraph.> And this is usual what you want.> The same is done internally if you use the Menu “Insert {fmin} Page break”, but the paragraph is split on the cursor position, some times unexpected.> Using the “Format {fmin} Paragraph” is more simple.>

In the plain text ZmL presentation the page or column break is written in a line before the paragraph as

This forces on back conversion to LibreOffice exact the above described behavior, a paragraph style with Insert Page break or column break before.> It is compatible and obviously.>

To simplify a page break in the current text, you should use the style TextPg or TextCol instead Text.> This is also done automatically by back conversion.>

Traditional often images are positioned as possible, depending of the page formatting.> For example Latex has its own free style to positioning images on a proper position in meaning of the Latex rendering, not in meaning of the user.>

But familiar in html (often used for technical documentation), images are always exact positioned in the text flow.> For technical documentation this may be important to have the images closed to its explanation.> Look her for example right side, there is the image spoken above.>

That’s why this converting system between LibreOffice and the plain ZmL text, which has a natural closed relationship between text and image because of their sequence in the plain text presentation, uses a simple presentation of images in LibreOffice: Images are always bounded to a paragraph which contains the image caption.> The position is left or right bounded, but with 0 distance to the paragraph.> If you move unintentionally the image in LibreOffice, go to its properties (right mouse) and entry 0.>0 for its position, and the image should be proper again.>

But there may be sometimes a problem: If the LibreOffice rendering for the page would insert a page break or column break at an inappropriate place near the image, then you should insert a manual page break or column break before the paragraph to which the image is bound.>

The figure right above is inserted with this shown style ImgCaptionTextCol.> It forces a column break before, as also see in the image.>

But you should taken care about the new column, it should be more filled that the column before, elsewhere the rendering may fill the columns in an equal kind and inserts an unexpected new column here.>

This handling should be done usual in the LibreOffice presentation.> Then you see the image close to the text in the plain text ZmL presentation too.> If you edit their, be careful with page breaks and column breaks, which are proper syntactically able to see in the plain text ZmL, and all is proper.>

The numbering of the images is done by the ZmL to LibreOffice converting, not from LibreOffice itself.> See chapter 3.8 Images page PDF@31, because the ImgCaptionText.>.>.> cannot support numbering.> The behavior of tables is similar to that of images Make sure that the page and column breaks are proper.>

LibreOffice has a little bit trouble if images are shifted with the mouse.> This is a concession to the user who wants to have free mouse positioning, but exact this breaks the relationship between text and images.> A second problem is handle image captions in a text box, with two sources of positioning errors.>

If you are concentrate to text writing with an office tool, you may be triggered to use a lot of nice styles for free possibilities for your design.>

But also for Asciidoc, html, most of other Markup sources, the style of the currently text is only one.> It has not a specific style dedication in the ZmL (and also not in the other markup languages), it’s only text.> The converter from ZmL to LibreOffice takes the Paragraph style Text (not Text Body) This style should be used and defined in LibreOffice.> The rule “less is more” produce a more relaxed design, concentrate to content, not to unnecessary "nice to have" but real not useful appearances.>

For Lists, usual the given list styles are used, which have the possibility to select different bullets etc.> But especially the bullets can be also part of the text itself.> This opens the opportunity to use a context related bullet, which can be also a specific text.> “Numbered list” with an auto incremented number in different styles are proper for common articles.> But for exact presentation of technical things, the number should be related to the text, should not be automatically incremented and hence changed if a new list item is added.> That’s why using a numbered list is not recommended in my mind.> Write the bullet appearance by yourself.>

All markup languages supports a numbered and an unnumbered list, also ZmL by using the familiar from Asciidoc known writing style

But it may be recommended not using a list style for lists, instead a specific paragraph style with the necessary indentation, and write the bullet manually.> This styles can be defined with any specific user name in your document, but the recommended style names are:

List1, List2, List1Left and List2Left are paragraph style names in this document.> copy or create this styles, but use this names.> In this kind some more specific paragraph styles can be used.> In ZmL there are written in form:

The format style is given first in the paragraph line.> The bullet can be coded in UTF{nbhy}8 in the text or used with the given subscription.>

\t ` with one following space presents the tabulator character.> The specific text style is written with [cZmL]<::cStyle:List1.>>`, whereby cStyle is the character style name in LibreOffice, see next.>

For using Asciidoc this is translated to:

The possibility of [.>List1] in Asciidoc creates in HTML:

It means it is presented by a so named division, which has a specific paragraph appearance controlled by the CSS script (Cascade Style Sheets for HTML).>

See also the ZmL definitions in 3.7 Code snippets page PDF@28

As also able to see above, Code snippets are often used in a technical software documentation.> The important feature is: The lines shouldn’t be wrapped.>

That’s why the source text should be limited in text line width.> For readability this is usual proper, because this code snippets are only snippets for illustration, and not the complete code ready to copy.> For such use the original source files.> Read and edit the sources in the proper IDE (Integrated Development Environment) to work with it!

But for that, of course, the code snippets should have, as often usual, a monospace font.> And also in the paragraph style the check box “Do not add spaces between paragraphs of the same style” should be activated.> Which Code paragraph styles should be given: This depends of your requirements.> You can define it by your own.> The default LibreOffice paragraph style Code should be used for common.> But for specific languages some styles below Code in the Hierarchy should be given:

The font styles may be identically, or different in bold or italic, for your own.> Usual the background color should be selected for recognizing the language.> This is not so proper but acceptable for a white/gray/black printed document, but proper for a pdf viewer.> Use a pastel color for the background.>

In Asciidoc code blocks are written as:

In ZmL the code snippets are presented as

This appears as:

ZmL allows designations of specific characters introduced with the back slash, especially \\ for the back slash itself, as also in other texts.> It supports also character styles, which are written as <::style:content.>>.> Hence the code blocks can also be styled.> Especially marker, here the (ret) helps for explaining the code in the text.>

Including sources:

But it is an effort to copy source content to the documentation and correct them, if the sources are changed.> Often this will be forgotten.> Asciidoc supports copying the content from referenced sources during HTML generation in the HTML, as very interesting feature for software documentation.> Also, in HTML this code is shown in a sub window with a horizontal slider.> But this is never usable in a printed document where LibreOffice is source of, and it’s also not possible in LibreOffice, its only for HTML view.>

In VmL and LibreOffice there is a similar way.> A ZmL script can contain:

this is similar as in Asciidoc where it is written:

Unresolved directive in LibreOffcZMarkup.adoc - include::../path/to/src.c[tag=label]

But VmL has additional features, see 3.7 Code snippetsPDF@28 page , also for markers.> And it shorts the line (because the sub window with slider is not applicable).>

But, of course, the sources should be prepared for this including:

For the last point there are some possibilities for markers and omitted lines in the ZmL include line.> See3.7 Code snippetsPDF@28 page .>

The usual used bold, italic, underlined, and also subscript and superscript character style dedications are all direct styles.> If you press ctrl+M (“Format {fmin} Clear Direct Formatting”) which may be sometimes necessary, this designations are removed.> Instead you should always use indirect character styles for that.> All of this possibilities are given with the indirect styles.>

But for compatibility and fast writing using the known hot keys as ctrl+I for Italic, the detected direct styles in a LibreOffice document are automatically translated to the necessary indirect style in the ZmL plain text.> While back conversion to LibreOffice you get the indirect formatting in LibreOffice for further working.> You should know that, you have not effort, and you have the possibility to change the appearance for all marked texts in a unique kind.>

The per default used character styles for the replacement of the direct styles are:

For this character styles which should only influence this given properties of the text, and not the font size etc.> LibreOffice works exact, but it hidden its exact working and it is error-sensible.> What’s happen: If you change the character style and you do not entry a new font or fount size, all is ok.> The font and its size is derived from the paragraph style.> But if you change the font for this character styles, it is changed.> You can never revert it to “derived font”.> This is a problem of LibreOffice, should be fixed.> But it is able to fix by manually handling of the internal styles.>xml respectively replace a changed styles.>xml by a proper one from another document, see 2.8 Exchange and maintain the styles of the document page PDF@21

Additional you should have all code fonts and backgrounds which are existing as Code paragraph styles also as character styles.> This allows refer to code snippets with the same writing style also in your currently texts.> This styles should start all with “c”, it is necessary for the ZmL conversion.> After the “c” for some standard code styles only one character should be written.> This is proper (but not necessary) for ZmL.> The character styles in ZmL are written generally as <::style:text.>>.> For example it is proper readable and writable: <::cC:float var; // C/++.>> which appears in LibreOffice as float var; // C/++; or <:cM:(M).>> for a marker in a source which appears as (M).>

But how? There a three levels:

The Javadoc itself may be satisfying, is it? It is satisfying to explain usage of a sub class or a specific operation.> Is it not satisfying explaining a tool written in Java?

And now it is nice to have to link from this explaining document to the Javadoc generated stuff, because both supplements each other.> Javadoc contains the exact description of an operations, or of a class, all what this does or contains, but it does not explain how and why to use.> For that the here written LibreOffice may be responsible to.> See also chapter 6 Internals page 48 in this document.> This may be an example how to explain the software.>

And now the request for the documentation:

If you open a pdf document in the browser, not downloaded, it is also sometimes possible to open a relative link in the document without problems if the destination of this relative link is on the same location in the internet.>

But sometimes, the relative linked destination, for Javadoc or other, is not available.> That’s why I place a relative link and a link to the proper internet location side by side in form: See WriteOdt.main(…​) (www).> Both refer the same content, local and in internet.> The local link may contain the class and operation, as shown here, the www does not need its repetition.>

3.11.2 Relative local links and supplement www link with same pathHow does it work {fmin} see PDF@38page

The problem is, that the link to an operation in Javadoc with a lot of arguments is sophisticated.> And if you change only one argument type, or add one argument more, while software development, the link gets faulty.> You should search and adapt it painful and expensively in your documentation.>

This work can be done automatically and is done by the ZmL / LibreOffice translator: The destination HTML file is read, all existing anchors are detected.> With them an internal index container is created with the key: Name of the operation, and value: complete anchor.> The problem of the overridden operations (different operations with the same name, but different argument types) is regarded in that kind, that non unique operation names are detected.> Only unique operation names are supported by this simple replacement.> But that is often sufficient.> Overridden operations should not be used too extensive for simple approaches, only if the operations are really similar and only distinguished by argument details.>

3.11.3 Supplement argument types of intern operation links (anchors in html)PDF@38How does it work {fmin} see page .>

The important basic consideration is: It should be based on plain source text.> The encoding should be UTF-8 to support also rarely letter also in LibreOffice without transliteration.> But for exception situations (using an old editor) also US-ASCII or ISO-8859-x (8 bit width character coding) should be possible.>

Some special non visible characters should be transliterated, see list in chapter 3.12 Transliteration of specific characters page PDF@40

There are only a few character sequences which controls the structure.> Outside of paragraph texts there are more possibilities, see 3.1.3 Section, chapter and paragraph structure near Asciidoc Inside a consecutive text (in a paragraph) only <::xxx.>> and the transliteration with \x is used.> This prevents confusion with text parts as in Asciidoc, the known Asciidoc’s text for a non interpreted text and its also confusing abbreviation +text+ is not necessary.> See 3.1.4 Text structure (syntax) similar Asciidoc but other designations page PDF@24.>

A line starting with // is ignored, but not inside a code block.> This is also true inside lines of a paragraph.> The comment line does not break the paragraph block.>

The block comment can be used also to disable blocks of text.> Nesting is allowed (TODO?).>

Comment lines cannot be transferred to the odt document and back again.> That’s way they are not really able to use.> It is only sensible, if the vml code comes from another source.> Then some things may be seen in this comment lines.>

Sections are parts of the document containing paragraphs and also complete chapters, which have a specific format.> Especially this is used for writing in columns.> Also have a specific background color for parts of the document is possible.>

The chapter and paragraph structure is basically similar in Asciidoc, Mark Down, Wikipedia text.> Here the basically chapter and paragraph structure of Asciidoc is used, with some specifics.> It means:

Inside a paragraph text and also all other texts (list items, chapter title etc) normal text is written as is.> The UTF-8 coding allows using also rarely specific characters.> Only specific character are transcribed, which are not able to show in normal text coding.> That are for example the non breaking space, UTF-16 coding \u00A0, written as {nbsp} in ZmL.> See chapter 3.12 Transliteration of specific characters page PDF@40

All character designations uses character styles of LibreOffice.> But there are some shortcuts for the standards, see chapter 3.13 Using Character styles, semantic text span at page PDF@41.> The general solution is writing in the text:

From here the page as two columns.> The style column2 is not a LibreOffice indirect style, it’s a specific style.>

Paragraph in format-style text as currently text, all lines is one paragraph as in other Markup languages.> Here character styles are possible, for example inline code snippet from Java language or just #define ClanguageMakro or also ”Quotation‟, Emphasis, Strong Emphasis

You can have references to chapter 3.2.1 Third level chapter, page PDF@26 or also to an external link Webpage vishia.org.> You can insert an image:

List of character replacement:

Code snippets are written as:

For the Language the styles of the odt file must have the proper CodeLanguage style as paragraph style.> Ones of the recommended language styles are

It is recommended that you should use a mono spaced font in the correspond odt file.> The paragraph style should not have spaces above and below the paragraph respectively no space between paragraphs of the same style.>

The code lines should be short enough, so that they are not broken.> Usual, the code is only a illustration of part of the explanation, and not a source of copy the code.> Hence shorten of lines may be possible.> But shorten lines should be marked as such:

The code snippet above is an example.> Because writing in columns, here only 45 character have place, but should be enough for this short presentation.> Use the full width (approximately 94 character on A4 page, writing width 18.>5 cm, with 10 pt font size) for elaborately code.>

This can be used especially for example to show markers as in the example:

Now you can use the same marker:

to explain the code line.> In ZmL this is:

This is the reason why a single backslash in the ZmL source code should be written with two backslashes.> A simple quotation mark remains a simple quotation mark with ASCII = 0x22, important for Strings in source code.> Whereas the specific left and right quotation marks should be written with \" and \'':

is in ZmL:

It is possible to include code snippets immediately from sources via link (recommended as relative link).> This is done if the odt file is generated from the given vml file.> The next text is the example how this appears in the documentation:

This shows a snippet from the named file.> In the real Java source file there are some marker written as:

Java source where the code snippet comes from:

The ZmL script contains:

whereby the <::include… line is one longer line till the ending .>>.>It means, this <::include… should be a part of the code block.>

How is it controlled which part of the source should be presented?

In the source code, usually in the comment, there should be a tag in the line where the code snippet begins.> That is the <:::main.>> in the Java source.> The main is given as tag name for the code snippet also in the <::include.>.>.> line in the ZmL script.> The source code line with this tag is included as first, but exclusively the tag itself, which should be written right side on the end of the line in comment.> If the include should start with the next line after this tag, write instead <:::~main.>>.> main is the tag name for this example.> If you write $ for the tag name, then the whole file is included.> But you can also use <::-$.>> <::+$.>> to omit lines, and <::.>$.>> and <::.>~$.>> to end including.>

The end of including the snippet is marked with <::.>main.>> respectively[cM]` <::.>~main.>> ` if this line should not be included also.> The ‘next’ and ‘not’ variants may be interesting if the source for the snippet cannot have end line comments, as for example Windows batch files.> Note, in Asciidoc you need for the adequate feature always an extra line for the “tag” which inflates code lines.> In Asciidoc tag::name[] should be written in one line before start including, and end::name[] to end the including block exclusively this tagged line.>

If some lines should be omitted, to shorten the documentation, then <::-main.>> can be written to stop on this line, and <::+main.>> to continue.> On the stop line always an ellipsis line + + .>.>.> is written for documentation.>

Last not least the source code can contain markers.> That should be written in the source code as <::@marker.>> as shown for <::@exit.>> and <::@exc.>> in the source example.> They appears in the documentation and can be repeated in the text to explain.> This is used in this document see 5.>1.>3 Macro ⇒ZmL and script -callOdt2ZmL.>bat and .>callOdt2ZmL.>sh page 42.>

But there is another interesting feature.> You can write also stop and start including and labels in the <::include:…, see next page.>

Syntax of the code include line

If you look to chapter 5.1.2 callZmL2odt.bat and callZmL2odt.sh at page PDF@48 you have an example how to use it.> The problem here is: A Windows batch file is given.> In a Windows batch file there is no possibility for end line comments, only lines can be commented beginning with REM or ::.> Hence it is not possible to write any marker in a active line, nor it is possible to write tags with start and omit in lines which are not comments.>

Another intension may be, you cannot change the code with this documentation stuff.> Only one tag may be admissible to find out the correct position for the snippet.> This can occur if another developer is responsible for the code.> You can only agree about the one tag, but not about some markers and omitted lines.> Not because your contributor is evil, no, only because it is effort to checkout and commit sources during the documentation phase.>

The syntax of the <::include.>.>.> line in ZmL is:

See the documentation in the chapter 5.1.2 callZmL2odt.bat and callZmL2odt.sh at page PDF@48 , compare it with the ZmL file of this documentation in look in the batch file, also in this working tree to have a proper example.> And try by yourself.>

For a printed document and also for pdf and inside LibreOffice the resolution of pixel depends on the output capability.> It is not related to the pixel size of the given image file.> The printer or render in pdf and inside LibreOffice adapts the pixel of the image to the pixel of the used output.> For that also anti-aliasing algorithm are usual used.> That’s why the pixel size does not play a role for the size of the image.> It may be interesting only for the resolution or quality of the image.>

The size is determined by the size on the output device or related to the paper format.> It is named in following text as "printed size".> That is either a value in cm, inches, pt or pica as usual units for that.> Only this size is used also internally for LibreOffice.>

But, sometimes the pixel size should be used to determine the printed size, if the image is changed or if the document is written newly, maybe to show one pixel of the image exactly by 1, 2 or 4 pixel in the printed output, maybe to have a relation to the image pixel size, or maybe also to prevent some aliasing effects on bad rendering.>

That’s why you can give the image size also in pixel with a related DPI ("dot per inch") resolution.> It the printed size as size=.>.>.> is not given, then this printed size value is calculated by translation to LibreOffice.>

For translation from LibreOffice.>odt to Plaintext.>vml.>adoc the pixel size is gotten from the image file (if it exists in the given link), and the DPI value is calculated with the given print size.> The DPI value may be an interesting information.> With this information you can tune the size of the image in your vml.>adoc file, for example tuning the DPI value, together with removing the information to force new calculation of the size.>

For example you see the following line:

Then you see, you have a fine resolution, because the image is small with a high number of pixel, but you see also that the image is a little bit biased.> The reason may be, the image was change in pixel size, but not in the document.> If you change this line to

The you force new calculation of the size in cm, whereby the size will be a little bit greater, because of reduced DPI.> But now the bias is removed, the original width and height relation is mapped.> And last not least for a printing output with 150 DPI exact three image pixel are used to build the print pixel.> On next generation from LibreOffice you will get the line

which is the real size now.>

If the size is given in the

then this given printing size value is used, independent of the image pixel size.> The additional pixel size and DPI value is ignored then.>

(empty page)

Because it is necessary to dedicate the bookmark labels by your own, it is in your response.> Generally the bookmarks are local for the document.> But because of the 3.9 Possibility of include and dispersion page PDF@34, the labels should regard the adequate correspond documents.>

It is recommended that labels should start with the same text of the main topic (chapter level 1), following by text parts for sub chapters, as:

But for that if you change your chapter structure, you should adapt the name of your labels.> Such refactoring may be sometimes necessary.>

Changing a given label means, you should adapt all usages.> This is not hard to do in the ZmL plain text {fmin} you can use search ‘n replace over some files.> But if you have published files, and the bookmark labels are also used for links from extern, it is problematically.> As compatible solution you can offer two bookmarks for one chapter:

If a chapter was referenced which has no label in the ZmL till now, an automatic label as <::#$Label_12.>> will be inserted.> Search and replace such labels on further working in ZmL editing.>

In LibreOffice writer the reference to another chapter of the same document can either be done as usual, with Cross Reference to “Headings” as also as shown in <<Img_LO-Asciidoc_DialogCrossReferences-1,Figure 8: DialogCrossReferences-1.png>> to manual given Bookmarks.> In the second kind you should know your bookmarks, because the Header texts are not displayed.> But both is compatible.> On creating ZmL the bookmark to a header in form RefHeading:12345 is replaced by the given known manual bookmark.> In both case the ZmL is written as:

For back conversion ZmL to odt the part after the label (here 1.>2 Title) is ignored.> This is only an information in ZmL to know what happen.> It means if the chapter title is changed, the current given chapter title is used for the next odt to ZmL conversion.>

If the page is given to a label (proper for a printed document, or also for pdf), the page should be placed after the referenced text, for example in form page 12, where the 12 is the inserted “Page number (unstyled)”.> For odt to ZmL conversion the following information is generated:

The 77 is only a place holder without meaning.> (in an older version the real number was output here, but the disadvantage is, that the ZmL source file is changed at many positions only because moved page numbers).> The back conversion ZmL to odt uses the label from the last <::@#ref:label.>> also for the page as label.> Backward compatible CR (Change Request): write either <::@page.>> or <::@page:label.>>

Follow 3.9 Possibility of include and dispersion page PDF@34.> If you produce a large document from more ZmL files, the bookmarks should be all internally.> If you produce more documents, one from one ZmL file, then the same bookmarks plays the role.> It means, bookmarks are used in the same kind as internal references as also for references in the other documents of the same suite.> But of course, for a link from one document to the other of the same suite, a link, not an internal reference is necessary for odt and PDF, and also HTML.>

How does it work, what to do?

First, the related documents should be in the same folder.> This folder should be given with the argument

The both paths are examples, but meaningful examples.> Regarding the generated user-ready documents: They are PDF and HTML.> They may be stored in the named path.> A side by side PDF document is reached with theOther.>pdf as also as .>.>/pdf/theOther.>pdf if both are contained in the pdf folder.> It means you can track the link from the generated document, and also from the odt if the .>.>/odt directory is beside the .>.>/pdf and .>.>/html.> This directories may organized as symbolic link to the original location, because the odt is anywhere in a source working tree.> For the directory tree, as example, see also 4.1 Directory tree structure in the working area PDF@42.>

Alternatively you can use

or also as absolute path possible in a local network.> This is sensible if the referenced documents are only able to find there, as absolute location.>

Then, the ZmL to odt conversion uses this path to create a hyperlink to the external document, instead the internal reference.>

But how to decide which label is external, and how to get more information? This is done during odt to ZmL conversion.> On any conversion from one given odt file its internal bookmarks are written in a file proper to the command line argument:

The * is replaced by the name of the converted document.> Hence you have the files

side by side.> Now the ZmL to odt conversion reads all this files exclusively the own file (with the own name), and hence it gets an internal list of all labels which are existing in the other, related documents.> The *.>Labels.>txt contains the label (bookmark), the chapter title and the page number.> The name of the file.>Labes.>txt is also gathered in the internal list of external labels.> So the link can completed with the name of the external file and the label as internal anchor (target).> Wit this information a reference to a related document is written as:

Example:

See also Internals_LibreOffcZMarkup.pdf: 1.4 WriteOdt on page PDF@3.>

This is a link to the related document.> The link is created in ZmL writing only:

Which label should be used, how the label is named: This is determinable by looking either in the other odt file, the name of the bookmark of the chapter, or also in the generated and given OtherDocu.>Labels.>txt file.> This is a one time effort.> If you do not change the bookmark labels (see 3.10.1 Use a proper name for bookmark labels pager PDF@353.10.1 Use a proper name for bookmark labels), then it is done for all time.> If you change your label texts, you should search and replace all occurrences, which is also a possible not to high efflort, as descibed in .>

The information about page, chapter title and number is gotten from the file Internals_LibreOffcVMarkup.>Labels.>txt which was written on last conversion from this odt file to ZmL.> But note, the information about chapter tile and page are only given if the odt file contains anywhere a Table of contents where this chapter is referenced.> This should be a matter of course.>

The generated information in the odt contains a complete link to the given HTML file, with the internal label (anchor), as also the reference to the given PDF file as local or global as hyperlink.> For PDF unfortunately there is no common standard concept for internal label selection.> Hence the user can select by its own the given chapter or page.> But if you read and have opened the documents anyway, you should familiar with the table of contents in PDF, often as tree left side, and you can find fast the related chapter and also the surrounding chapters.> The chapter title and page number is marked with the character style Reference which may be conspicuous.>

On back conversion from odt to ZmL this given information in odt are translated to a ZmL link:

The information in the <::ref:…: After the label till .>> are optional, not used for ZmL to odt conversion, but they are an important information while reading the ZmL file.>

Hyperlinks are written in ZmL as

or also as absolute or internet link:

The link can also have a target or anchor designation in the known style from HTML or also used in LibreOffice in the link dialog:

This links are converted in LibreOffice.>odt in this adequate kind.> Unfortunately the targets does not work in LibreOffice for relative links (Document links).> They only work for the links to the internet.> It is a bad feature which complicates proper software documentation.>

As mentioned in 2.7 External links to Javadoc local files and the internet page PDF@19 But sometimes, the relative linked destination, for Javadoc or other, is not available.> That’s why I place a relative link and a link to the proper internet location side by side in form: See WriteOdt.main(…​) (www).> Both refer the same content, local and in internet.> The local link may contain the class and operation, as shown here, the www does not need its repetition.>

As argument on translation you need:

In the ZmL you can write the link to the adequate operation as:

Then the ellipse in the given www link /.>.>.> is replaced by the String after all back path characters / and .>[cZmL].> or .>, the start of the real used path.>

For back translation from odt to ZmL it is tested whether the www link starts with the given argument -www:https:myWeb/dir.> If it is so, then also the rest of the path is compared as stored in the content.>xml in the odt file.> This depends of course from handling in LibreOffice.> If they are equal, the ellipse is created again for VmL.> On translation in both direction it works anyway.>

The requirement is described in 2.7.3 Supplement argument types of intern operation links (anchors in html) page PDF@20

The ZmL translator searches the HTML file as given in the link.> It should be (also for the proper link) the relative path starting from the odt.> From the HTML file all anchors are checked and write in an index container.> If the anchors refer to an operation, the key of the index is the operation name.> If the operation is not unique, means the same name is found twice or more, then the first occurrence is preserved, but a “?” is appended on end.>

For ZmL to odt translation:

For odt to ZmL translation

The link for unique operations may look like:

The text of the link is not changed and not used.> It may be nice to do not write there the formally arguments, instead mnemonic argument descriptions.>.>

Why using a build or just temporary location? See 4.1 Directory tree structure in the working area page PDF@42.> The idea is, that the temporary location should be a part of the working tree.> This is possible using a symbolic linked directory.> The working tree may be on a network location, and the link destination for build should be local, or as I prefer, on a (local) RAM disk.> That is done by the script in src/example/odt/makeScript/​+createCleanBuild.>bat.>

This build directory may be unnecessary by setting some arguments only using the source directory, see next chapter.>

This is the script in the TemplateZmLodt-2024-09-28.>zip in src/example/odt/makeScript/​+createCleanBuild.>bat.> Because showing in column width only a few lines are broken marked with .>.>.> on end and begin of the continued line.> If you copy this content from the documentation, remove this line break with the .>.>.>, then it is complete.>

This script is called from a specific batch file, see 4.>3 Convert from given vml to a new odt page 30.> It is called with only %1, the name of the vml and odt file:

You should adapt the line for the Shell start, the directory of the batch file.>

A batch file .>.>.>/odt/makeDocu/LOffc_odt2ZmL.>bat for Windows-PC ( possible of course also a shell script) is stored in the shown local directory.> This script can be the same for all conversions, but can be adapted for tests and should be adapted in some special arguments, see description below.>

This should be explained.>

The core action is (JAVA) call java with the class org.>vishia.>odt.>readOdt.>ReadOdt .> But because this batch file is globally valid the arguments should be prepared with environment variables.> They are shown on (ENV).> The a little bit sophisticated one is the BUILDCMPN.> This is the directory where some temporary files and backup files are stored.> I use for that a RAM-Disk which has the advantage, it is faster, and does not does not consume the lifetime of a hard disk or SSD.> The amount of stored data is in kByte till MByte range for a vml file.> For this solution a build directory beside src in the working tree is presumed but prepared.> The build is a symbolic link (Junction in MS-Windows) to the TMP directory, and the last one is on RAM-Disk.> There is a small batch script +clean_mklink_build.>bat to clean and prepare this build:

This is a universal batch, only the location on the used directory inside %TMP% should be determined.> It creates a symbolic link in MS-Windows and before, it cleans all.>

If you start this batch you have a cleaned situations, but you have also lost all your temporary files inside the build.>

The Java arguments (Java Args) should be explained: Usual arguments are part of the command line.> But this very long command line will get non obviously.> Hence inside Java there is the possibility to read arguments from any file.> This file is given with --@path/to/file and this is exactly this same file.> With additional the label --@path/to/file.>args The identifier args is searched in this file on the first few positions on beginning of lines.> The string before, here :: is recognized as indentation or marker string, for the batch file it is the comment designation.> And last not least also the comment sequence for arguments is declared in this line her with ##.> All immediately following lines with the indentation, here :: are lines for arguments.> Environment variables are also dissolved if they are written as $(ENV) or also only $ENV if it is unique as identifier.>

But all in all, this files runs, produces a simple output on pressing the icon button: