General documentation style/source improvements

Things to consider:

• Styling
  • Proper/consistent use of layout macros, e.g. menu, kbd, btn.
  • Get rid of table/figure references and titles.
    • They are numbered in the single-page HTML output, and thus a bit weird if we split it and not renumber them. Also, for LaTeX that moves the figures around, references and titles make sense, but for AsciiDoc HTML/PDF output the order is as in the source file.
    • We can say things like "... as in the following figure:" and then immediately put the figure after that.
    • This mostly concerns Chi, but we should check all documentation sets.
• Documentation source layout
  • Everywhere exactly one empty line separation, except two empty lines before new section?
  • Single sentence per source line, for simpler reviewing (less irrelevant diffs).
• AsciiDoc features
  • Use * for unordered lists instead of -. See also #54 (comment 303258).
• Other
  • Use https instead of http in links where relevant.

changed milestone to %v0.2

added CIF Chi Products SeText ToolDef labels

added TypeEnhancement label

changed title from General documentation improvements to General documentation style/source improvements

assigned to @freijnen

I got the single sentence per source line working.

Now, I try to come up with some styling rules. So far I have:

• Itemize items should be preceded and succeeded by an empty line.
• Itemize items should always be *, never -.
• Code block should be preceded and succeeded by one empty line (currently always preceded by 2).
• Table should be preceded and succeeded by one empty line.
• For section headers:
  • When preceded by text, two empty lines between text and section.
  • When preceded by a label, one empty line between text and label, no empty line between label and section.
  • When preceded by an indexterm, one empty line between text and indexterm, one empty line between indexterm and section
  • When preceded by a label and an indexterm, one empty line between label and indexterm.
  • Section header should always be succeeded by an empty line.

Does that make sense?

This makes sense. Note that some of these have semantics. I think the label and section header must never have an empty line in between as otherwise it doesn't work. So please check that the rules result in properly working/rendered documentation.

Some practical concerns/ideas:

• I propose to resolve each separate issue in a separate branch. E.g. reworking the 'per source line' separate from other things.
• Also, we should check in-progress/open branches and merge requests, to not miss anything.
• Let's do the styling rules in separate branches or at least separate commits, to keep it reviewable.

Oke that makes sense. In that case, I will make sure this change only includes the per source line.

I used a .tooldef script to do this. This can be used to update the other branches (plant invs, no LP for auts with one loc, and rail diagram) as well.

mentioned in merge request !83 (merged)

mentioned in commit 9c457e87

unassigned @freijnen

This is not super urgent. Let's postpone to %v0.3.

changed milestone to %v0.3

changed the description

changed milestone to %v0.4

changed the description

assigned to @freijnen

@freijnen If you're going to pick this up, base it on the branch for #35 (closed), as a bunch of AsciiDoc files got changed there.

Should I wait for the merge request until #35 (closed) is accepted? Or do I merge into #35 (closed)?

Make a branch on top of the branch for #35 (closed). You can already make a merge request now, or wait until #35 (closed) is done. If you create one now already, you can request a review now already as well.

Definitely don't merge the merge request to the branch for #35 (closed), because then that branch and merge request get all those changes as well and thus a huge diff! Maybe even keep your merge request in 'Draft' status to prevent accidental merging.

Once the merge request for #35 (closed) is merged, that branch will be gone, and your branch that builds on top of it will automatically be retargetted by GitLab to develop. You can then remove the 'Draft' status and it is then a merge request like all others.

Do note that I've made even more changes to AsciiDoc files as part of #35 (closed), and more may follow while addressing review comments. You may get conflicts and may have to do some rework to resolve them if you start on this now.

Ok, thanks for explaining. I'll check once #35 (closed) is merged to see if conflicts need to be resolved.

mentioned in commit 2da8ed2e

mentioned in commit e70b3874

mentioned in commit ae175abc

mentioned in commit 787fd14a

@freijnen I see you're working on this already, so it may be too late, but: I would prefer separate branches for each of the points to address, to easy reviewing the changes.

Ah, it's too late for that. I also thought it would be better to put "Documentation source layout" in a separate branch.

I did commit them as separate commits where the commits are independent. So you could review it per commit maybe?

It is good that you used separate commits. However, if there are review comments, these will be addressed in subsequent commits, and then it is difficult to see specific changes across multiple commits with other commits in between.

mentioned in merge request !171 (merged)

mentioned in commit 38cc20d3

mentioned in merge request !172 (merged)

mentioned in commit a742aaba

mentioned in commit 0425c9f7

mentioned in commit 8c334de6

changed the description

I changed the description to use checkboxes to indicate completed parts, rather than strikethrough, as that makes it seem like we no longer think the completed parts are a good idea.

mentioned in commit cc7b631b

changed the description

unassigned @freijnen

changed the description

Asciidoctor supports defining unordered lists with asterisks (*) or with hyphens (-). They do the same thing, except that asterisks can be used for nested lists, whereas hyphens cannot. In our documentation, we use both. I propose to change everything to asterisks, for consistency. Also see: https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/

Sounds good. I've added it to the issue description. (note that we don't get emails about changes to issue descriptions)

mentioned in commit 8c7d49e7

mentioned in merge request !179 (merged)

changed the description

assigned to @freijnen

I've reassigned this issue to @freijnen, seeing !179 (merged) was created.

mentioned in commit 747e5eef

marked the checklist item Use * for unordered lists instead of -. See also #54 (comment 303258). as completed

unassigned @freijnen

mentioned in issue #254

assigned to @freijnen

mentioned in commit cf370e4b

mentioned in commit 96d216e0

mentioned in merge request !215 (merged)

mentioned in commit 2827cbc3

changed the description