Skip to content

How to make manuals

Text modifications should be done in the .adoc files.

Screenshots, on the other hand, are not taken manually: they are taken by the screenshots-* "tests".

The makefiles do use tools (../tools/*.py) in order to: - list the .adoc dependencies (that lets us have nicely structured documentation, split across multiple folders) - "map" the screenshots from their path in the .adoc file, to an actual place within the tests results (this implies tests must be run before re-generating the documentation.)

This means the makefiles have proper, "hard" (albeit generated) dependencies to screenshots that must have been produced by corresponding test(s).

Building

  • First, run all screenshots-* tests.
  • vault/docs/hvui $ p4 edit ...
  • vault/docs/hvui $ make
  • (make sure the document looks good)
  • vault/docs/hvui $ p4 revert -a ...

NOTE: If you happen to be running tests in a non-standard folder, you have to specify that to the makefile: make TESTS_DIR=~/tmp

Conventions

Screenshots paths

Asciidoc is ... not perfect. When it comes to screenshots, it has what some would consider broken rules for resolving relative paths.

Consequently, it can be necessary to set the imagesdir when working across folders.

XREFs & identifiers

Similarly, although Asciidoc provides a supposedly neat way of cross-referencing sections in sub-documents (i.e., other .adoc files), the reality is that it won't work if you are trying to reach identifiers placed in a file that's not within the directory [sub-]tree as the toplevel .adoc file (e.g., when referencing shared "concepts".)

Thus, this: https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/ simply doesn't work for us (see CL#131224)

We have to resort to our own, somewhat loosely defined, "qualified identifier format", consisting of <identifier>[.<identifier>]*.

E.g., [[site.top]]

Action identifiers

Actions IDs should consist of actions.<name_in_actions_list.cpp> e.g., actions.diff_vault_local

Actions# with personality disorders

Some actions have completely different labels, and will perform [slightly or vastly] differently in different contexts:

  • "Commit"
  • "Scan and commit"

…but are actually the very same action.

Those 2 labels will be set to the same action (because it makes sense to consider those as the same actions in terms of code), but for the user they look like entirely different, and do different things.

Since we must document the 2 facets of that action, we must have 2 entries in the actions documentation, with possible IDs:

actions.commit actions.scan_and_commit