== Technical guidance


=== For authors

NOTE: This section provides some basic technical orientation for authors commissioned to write documents. Both the https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer's Guide] and https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoctor User Guide] provides much more detailed and comprehensive references for how to work with this lightweight markup format. 

[structure]
==== Structuring the document

All documents whose primary language is English start from the file `index.en.adoc`.  Using the https://docs.asciidoctor.org/asciidoc/latest/directives/include/[`include` directive] allows a single document to be spread across multiple files.  This makes editing (especially collaborative editing) easier, helps translators, and simplifies reordering sections of a document.  

Except for the primary file being called `index.en.adoc`, there are no hard restrictions on how a document must be structured.  It is probably easiest for editors to structure documents with number-prefixed filenames, preferably with large intervals to allow new sections to be inserted.

----
├── index.en.adoc
├── 100.en.adoc
├── 200.en.adoc
├── 250.en.adoc <1>
├── 300.en.adoc
└── 400.en.adoc
----
<1> This file was presumably added later, between `200` and `300`.

Another option is to include a brief heading in the filename, but using the number prefixes so the files are displayed (including for translation) in a sensible order:

----
├── index.en.adoc
├── 0100-introduction.en.adoc
├── 0200-elements-for-describing-a-location.en.adoc
├── 0300-the-georeferencing-process.en.adoc
├── 0400-collaborative-georeferencing.en.adoc
├── 0500-sharing-data.en.adoc
└── 0600-maintaining-data-quality.en.adoc
----

See the section on <<translation,translating documents>> when adding, changing or deleting document files.

[asciidoc]
==== Writing in AsciiDoctor

AsciiDoctor is a text document format for writing (among other things) books, ebooks, and documentation. It is similar to wiki markup — if you can write a Wikipedia article, then you’ll have no problem with AsciiDoctor.

.AsciiDoctor User Guide
[TIP]
====
The https://docs.asciidoctor.org/asciidoctor/latest/[AsciiDoctor User Guide] provides an excellent reference to what's possible with AsciiDoctor.
====

Here are the most common parts of AsciiDoctor markup:

[text]
===== Text

Regular paragraph text does not need any special markup in AsciiDoctor. Just add a blank line both above and below each paragraph, and the first word in the paragraph should not have a space before it. Here are some example paragraphs in AsciiDoctor:

----
This is an example paragraph written in AsciiDoctor. See, it's just plain text; no special markup necessary! Do make sure there aren't spaces or manual indentations at the beginning of your paragraph text.

This is a second example paragraph in AsciiDoctor. Note that there's a line break and a blank line between paragraphs.
----

[[chapters]]
===== Chapters and headings

The top of each chapter file should begin with a chapter title preceded by two equals signs. It's good practice to always include a unique ID string above the chapter title, surrounded in double brackets, for example:

----
[[unique_chapter_id]]
== Chapter Title
Chapter text begins here.
----

The unique ID string is used to link directly to a chapter or section, such as <<chapters,this link to this section>>.  Readers can also link directly to a section, by using the § link that appears when the mouse hovers over a chapter heading.

[toplevel]
===== Top-level heading

Within a chapter, the first and highest heading level uses three equals signs:

----
=== Top-Level Heading
----

Lower-level headings continue with additional `=` signs.

_https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/[Continue reading about section headings in the AsciiDoctor User Guide]._

[inline]
===== Inline Markup
Here are some standard typographical conventions with explanations of how they're commonly used:

`+_Italic_+` One underscore character on either side of text marks it as _italics_ in AsciiDoctor.

`+*Bold*+` *Bolded text* is used to emphasize a word or phrase. The AsciiDoctor markup is one asterisk on either side of the text to be bolded.

`pass:[`Constant Width`]`
Constant width, or `monospaced`, text is used for code, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. The AsciiDoctor markup is one grave accent sign on either side of the text to monospaced.

Hyperlinks:
For hyperlinks to external sources, just add the full URL string followed by brackets containing the text you'd like to appear with the URL. The bracketed text will become a clickable link in web versions. In print versions, it will appear in the text, followed by the actual URL in parenthesis.

The markup looks like this:

----
Visit https://www.gbif.org/[GBIF.org].
----

_https://docs.asciidoctor.org/asciidoc/latest/text/[Continue reading about text formatting in the AsciiDoctor User Guide]._

[admonitions]
==== Admonitions

AsciiDoctor allows authors to call out supplemental admonitions in the form of notes, tips, warnings and cautions.

For a note, the markup looks like this:

----
[NOTE]
====
Past trends are no guarantee of future performance.
====
----

And here’s how it renders:

[NOTE]
====
Past trends are no guarantee of future performance.
====

There is also a short form, which is appropriate for a single sentence:

----
NOTE: Past trends are no guarantee of future performance
----

_https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[Continue reading about admonitions and other block formatting in the AsciiDoctor User Guide]._  The guide also covers other formatting, such as bulleted or numbered lists, tables and images.

==== Converting or importing an existing document

There are tools to convert documents from other formats into AsciiDoctor markup.  The AsciiDoctor manual has a https://docs.asciidoctor.org/asciidoctor/latest/migrate/ms-word/[section for this] using command-line tools.  There are also online converters:

* https://alldocs.app/convert-word-docx-to-asciidoc[MS Word (DOCX) to AsciiDoctor] (Google Documents can first be exported in MS Word format)
* https://alldocs.app/convert-openoffice-odt-to-asciidoc[OpenOffice (ODT) to AsciiDoctor]

Generally, manual review of tables, links, crossreferences and so on is required after the conversion.

==== GBIF extensions to AsciiDoctor

The document system recognizes some small additions to standard AsciiDoctor markup.

===== Terms
Terms, including Darwin Core terms, can be shown in a special style and with a link to the definition as term:dwc[decimalLatitude] or term:dwc[dwc:eventDate].

----
term:dwc[decimalLatitude] or term:dwc[dwc:eventDate]
----

===== Table cell wrapping

By applying the role `break-all`, the contents of a table cell will break (wrap) at any position, rather than only between words.

[cols="3"]
|===
h| DNA sequence example
| [.break-all]#TCTATCCTCAATTATAGGTCATAATTCACCATCAGTAGATTTAGGAATTTTCTCTATTCATATTGCAGGTGTATCATCAATTATAGGATCAATTAATTTTATTGTAACAATTTTAAATATACATACAAAAACTCATTCATTAAACTTTTTACCATTATTTTCATGATCAGTTCTAGTTACAGCAATTCTCCTTTTATTATCATTA#
a| The markup is `+++[.break-all]#TCTA…ATTA#]+++`

Without it, the DNA sequence would stretch the table cell beyond the width of the page.
|===

==== Outstanding issues

* Demonstrate embedding an image, and alternative (translated) images (https://doi.org/10.15468/doc-z79c-sa53[doc-effective-nodes-guidance] has this)
* Apply a custom style to the document (https://doi.org/10.15468/doc-z79c-sa53[doc-effective-nodes-guidance] also has this)
* Document a release process, possibly involving assigning DOIs.

=== For editors

[[source_code]]
==== Document “source code”

The plain text files and other assets (images, data tables) that form each document comprises the _source code_.

These source files are stored in a _Git repository_, which (for GBIF) is managed by a commercial service, _GitHub_.

The source code for this document is stored at https://github.com/gbif/doc-documentation-guidelines/, the source code for this part of the document can be seen https://raw.githubusercontent.com/gbif/doc-documentation-guidelines/master/600.en.adoc[here].

Contributors can edit the source code either in a web browser using the GitHub interface or on a computer (including when offline) using Git. They may also submit https://github.com/gbif/doc-documentation-guidelines/issues[issues] that comment or flag problems for others to address, including outdated information, broken links, misspellings and the like.

NOTE: Many tutorials for using both Git and Github are available on the web.

==== Document versions

Some documents are published as multiple versions.  This is done using _branches_ in Git: the name of the branch, such as `1.0` or `2019`, is the identifier for the version.  This allows for edits to old versions, such as updating a link or correcting a syntax error in the document.

The version (branch name) is used as part of the URL for the document, e.g. https://docs.gbif.org/effective-nodes-guidance/1.0/[https://docs.gbif.org/effective-nodes-guidance/**1.0**/].  This allows for multiple versions to be retained on the webserver.

[[translation]]
==== Translated documents

The translation system uses `.po` “_Portable Object_” files, which are commonly used for translating software and websites.

. A file `po4a.conf` needs to exist, as shown in <<translation-setup>>.  Each `*.en.adoc` file needs an entry in `po4a.conf`:
+
--
----
[type:asciidoc] 100.en.adoc $lang:100.$lang.adoc
----
The build system will warn if any `*.en.adoc` files are not present in `po4a.conf`.  (This is why the `README.adoc` and `LICENSE.adoc` files, not part of the document, do not include `.en` in their filenames.)
--

* Whenever the document text is changed, the build server will update the translation template file `translations/index.pot` with the source (English) text.
* Crowdin will detect the change to `translations/index.pot` and notify translators.
* As translators add translations to the text, Crowdin will make a pull request on the repository.  This should be merged.
* The build server will then rebuild the document with the translated text.

.Alternatives to Crowdin
[%collapsible]
====
It is also possible to translate documents without Crowdin, using desktop tools instead.  The translators then need to use Git/GitHub.  These additional steps are needed:

. For a new language, copy the generated `index.pot` (_Portable Object Template_) file to the new file `xx.po`, where `xx` is the https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes[language code].  For example this would be `da.po` for a Danish translation.
. To update a translation, open the `xx.po` file in a po-file editor and choose the option to “Update from POT file” or similar.
. Use a po-file editor to make the translations.  Examples are https://poedit.net/[Poedit] (software) or https://localise.biz/free/poeditor[poeditor] (website).
. Use Git/GitHub to replace the old translation file with your updated translation file.
. Push the changes, and the build server will rebuild the document

*It is not recommended to use both methods on the same document.  If translations conflict they would not be lost, but the resulting mess can be confusing to sort out using Git.*
====

==== Publishing a document

Here, publishing a document means building the document for `*docs.gbif.org*`, rather than the test system `*docs.gbif-uat.org*`.

To publish a document, go to the GitHub repository in a web browser.

1. If required, review and merge any translation pull requests.
2. Check the most recent output from the document build in Jenkins.  This is easily accessed using the "Build Status" button on the repository.  Check for
  * Incorrect spelling
  * Warnings about broken crossreferences
  * Warnings about incomplete translation
3. Review the document on https://docs.gbif-uat.org/, including the PDF.
4. Use the GitHub interface to make a _release_.

=== The documentation system software

The documents combine several small Linux tools:

* Git, for source control,
* https://asciidoctor.org/[AsciiDoctor], chosen with essentially the same reasoning as https://github.com/KiCad/kicad-doc/blob/5.1.0/doc_alternatives/README.adoc[the KiCad documentation authors] (and following their approach to translation),
* http://aspell.net/[GNU Aspell], for spell checking,
* https://po4a.org/[po4a], for translations,
* https://builds.gbif.org/[GBIF's Jenkins server], for document compilation,
* Docker, to ensure consistent builds,
* Apache, to serve the finished documents.

The result is mostly contained in a https://github.com/gbif/gbif-asciidoctor-toolkit[Docker container], with some integration in the Jenkins build job.

==== Generating the document

The source `.adoc` files in the repository are converted into the finished HTML and PDF documents using the _AsciiDoctor_ tool.  Every time a change is made to the repository, the https://builds.gbif.org/[GBIF build server] is notified.  It retrieves the document source code, generates the document (in HTML and PDF, and in all available languages), then copies the formatted documents to a webserver.

A log file of recent builds is kept by the build server.  If there is a syntax error preventing the document from being generated, you may need to inspect the log file to see what the problem is.  The log file also contains a list of possible spelling errors.

==== Local document build

If you are familiar with software development tools you can build a document on your own computer — this is useful for previewing changes.  You will first need to setup https://www.docker.com/[Docker].  Then, open a terminal window and navigate using the `cd` command to the top-level directory of your document — for this document, it would be `doc-documentation-guidelines`.  You can then build the HTML document with this command:

[source,shell]
----
docker run --rm -it --user $(id -u):$(id -g) -v $PWD:/documents/ docker.gbif.org/asciidoctor-toolkit
----

Assuming all is well, the resulting documents are in subdirectories coded by language (such as `en`), including both HTML and PDF files.  The output from the command should provide clues if there are problems.

You can also add `continuous` to the end of this command.  This will rebuild the document every time it is changed.
