Fixes doc auto-formatting oopsies #41342

samueldr · 2018-06-01T00:55:45Z

Motivation for this change

Documentation

(And other such examples can be found, see fixes.)

Man pages

NIXOS-INSTALL(8)                                      NixOS Reference Pages                                     NIXOS-INSTALL(8)
NAME
       nixos-install __ - install bootloader and NixOS
SYNOPSIS
       nixos-install [-I path] [--root root] [--system path] [--no-channel-copy] [--no-root-passwd] [--no-bootloader]
                     [{--max-jobs | -j }number] [--coresnumber] [--optionnamevalue] [--show-trace] [--help]

       --optionnamevalue
           Set the Nix configuration option name to value.

Some options were broken like --optionnamevalue here.

This fixes them and ensures xmlformat won't.

Explanation

The xmlformat documentation has these passages:

[19:55:42] <samueldr> Within a normalized block, runs of whitespace are converted to single spaces. Leading and trailing whitespace is discarded. Line-wrapping and indenting may be applied.
[19:55:53] <samueldr> In a non-normalized block, text nodes are not changed as long as they contain any non-whitespace characters

Open questions

Fixer tool

Should the fixer script be included in the repo the way I did it?

I'm really unsure. The commit was added mainly to show how it was fixed. I believe the commit can be safely git rebase dropped from the history. I'm ready to remove traces of the tool from the history :).

Though, there is some value in having a tool that passes the XML files through ruby+REXML: it would normalise some stuff in our files. Those normalisations haven't been added to the commits, but it would mainly ensure one type of quotes would be used (configurable) and would fix some XML weirdness that xmlformat doesn't care about.

The separate tool for more fixing can and should be discussed in a separate issue I believe.

Things done

Fixed the definition
Added the fixing script
Ran the formatter
Ran the fixer
Re-ran the formatter

This was done for both the doc and nixos/doc folders, and where there was changes, a commit was made. Do note that make format was ran until there were no more changes, as xmlformat apparently isn't idempotent, or at least, its output isn't deterministic in a way that re-running it can lead to more changes.

Once all fixed, I did a high-level visual overview of the generated HTML, it looks like everything was caught, but it's hard to be entirely sure. If there are other sections exhibiting the same breakage, the fix is known.

The changes have been made to 18.03 as this break manpages and documentation.

See #41344

To test / check

I would HIGHLY suggest reading each commit as otherwise all the XML soup will quickly make you dizzy.

✔️ Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS)
Built on platform(s)
- ✔️ NixOS
- ❌ macOS
- ❌ other Linux distributions
❌ Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
🆖 Tested compilation of all pkgs that depend on this change using nix-shell -p nox --run "nox-review wip"
🆖 Tested execution of all binary files (usually in ./result/bin/)
✔️ Fits CONTRIBUTING.md.

cc @grahamc as we went back and forth looking at the issue; I would like someone else to take a look at the PR too.

samueldr · 2018-06-01T00:56:42Z

~~I know about the merge conflict, I rebased on channels/nixpkgs-unstable, give me a few minutes to re-do the things with master~~

The other definitions broke term, cmdsynopsis and arg tags; spaces inside were removed, making workdsrun-ininstead of keeping them spaced.

This script is used to automatically fix issues within xml documentation files. The script is *for now* intended to be used ad-hoc, and the commits to be examined. A future discussion will define whether: * This commit and scripts are kept. * The script is extended for common use. The biggest issue right now with the script is that it *could* in theory destroy a valid space-less varlistentry. The script could, in practical use, be changed and extended to normalize some parts of the XML files, mainly: * A common quoting style for attributes * Fix-up some weird formatting automatically that xmlformat doesn't catch

With visual inspection that nothing got worse.

grahamc · 2018-06-01T13:38:18Z

doc/coding-conventions.xml

-     <term>Else:</term>
+     <term>
+      Else:
+     </term>
     <listitem>
      <para>
       <filename>misc</filename>


I sort of think none of these should be <term>. What do you think?

That if they are or aren't should be fixed in another PR :).

Though, it seems right in how it may be abusing the variablelist for its appearance instead of its meaning. Except variablelist could be more apt if instead of presenting it as a list of choices, it was more a description of the categories.

variablelist from TDG:

A list in which each entry is composed of a set of one or more terms and an associated description.

Doesn't make me think it's "programming" variables only. Looks like it's a catchall "term / definition" list. And it does look like term is the only node in there that isn't the definition.

So (while this may be wrong WRT valid docbook) this may be turned outside in this way:

<term> <filename>development/interpreters</filename> </term> <listitem> <para> If it’s an <emphasis>interpreter</emphasis>. (e.g. <filename>guile</filename>) </para> </listitem>

grahamc

LGTM merge away. I think the non-term terms can remain, despite not being really sematically correct.

grahamc · 2018-06-01T13:40:40Z

doc/multiple-output.xml

-     <term><varname>
-        $outputInfo</varname>
+     <term>
+      <varname> $outputInfo</varname>
     </term>
     <listitem>
      <para>


note this is adding an extra space after <varname>, maybe it is fixed in a future commit

This isn't adding an extra space after <varname>, but condensing the run of spacing into one.

grahamc · 2018-06-01T13:41:25Z

doc/package-notes.xml

-      <term>Java</term>
+      <term>
+       Java
+      </term>


I think none of these should be <term>s too

grahamc · 2018-06-01T13:42:17Z

doc/stdenv.xml

-      <term>Directories in the Nix store</term>
+      <term>
+       Directories in the Nix store
+      </term>


The above three shouldn't be terms

samueldr · 2018-06-01T13:56:23Z

As for fixing existing semantic markup, I really think it should be done in another PR; this is hard enough to review :).

samueldr requested a review from nbp as a code owner June 1, 2018 00:55

GrahamcOfBorg added 6.topic: nixos 8.has: changelog 8.has: documentation 2.status: merge conflict labels Jun 1, 2018

samueldr added 6 commits May 31, 2018 21:02

doc: Adds rule to xmlformat to help keep spacing right.

aa59151

The other definitions broke term, cmdsynopsis and arg tags; spaces inside were removed, making workdsrun-ininstead of keeping them spaced.

doc: ran make format

a45edd9

With visual inspection that nothing got worse.

nixos/doc: ran make format

88ca2b1

With visual inspection that nothing got worse.

nixos/doc+man: Fixes squishedtogether definitions.

15fa70c

doc: Fixes squishedtogether definitions.

6bf5419

samueldr force-pushed the fix/doc/formatting-oopsies branch from e722899 to 6bf5419 Compare June 1, 2018 01:10

GrahamcOfBorg added 10.rebuild-darwin: 0 10.rebuild-linux: 0 and removed 2.status: merge conflict labels Jun 1, 2018

samueldr mentioned this pull request Jun 1, 2018

Fixes doc auto-formatting oopsies [18.03] #41344

Merged

grahamc reviewed Jun 1, 2018

View reviewed changes

grahamc approved these changes Jun 1, 2018

View reviewed changes

xeji merged commit c958516 into NixOS:master Jun 5, 2018

samueldr deleted the fix/doc/formatting-oopsies branch July 9, 2018 00:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixes doc auto-formatting oopsies #41342

Fixes doc auto-formatting oopsies #41342

samueldr commented Jun 1, 2018 •

edited

samueldr commented Jun 1, 2018 •

edited

grahamc Jun 1, 2018

samueldr Jun 1, 2018 •

edited

grahamc left a comment

grahamc Jun 1, 2018

samueldr Jun 1, 2018

grahamc Jun 1, 2018

grahamc Jun 1, 2018

samueldr commented Jun 1, 2018 •

edited

Fixes doc auto-formatting oopsies #41342

Fixes doc auto-formatting oopsies #41342

Conversation

samueldr commented Jun 1, 2018 • edited

Motivation for this change

Documentation

Man pages

Explanation

Open questions

Fixer tool

Things done

To test / check

samueldr commented Jun 1, 2018 • edited

grahamc Jun 1, 2018

Choose a reason for hiding this comment

samueldr Jun 1, 2018 • edited

Choose a reason for hiding this comment

grahamc left a comment

Choose a reason for hiding this comment

grahamc Jun 1, 2018

Choose a reason for hiding this comment

samueldr Jun 1, 2018

Choose a reason for hiding this comment

grahamc Jun 1, 2018

Choose a reason for hiding this comment

grahamc Jun 1, 2018

Choose a reason for hiding this comment

samueldr commented Jun 1, 2018 • edited

samueldr commented Jun 1, 2018 •

edited

samueldr commented Jun 1, 2018 •

edited

samueldr Jun 1, 2018 •

edited

samueldr commented Jun 1, 2018 •

edited