NixOS docs: making it easier to hack on #39649
Conversation
|
Can the pre-build docs be autoformatted - something like gofmt or prettier? Not sure how much whitespace matters with XML but it can affect people's editing experirence. Last time I edited the docs, I found myself adding linebreaks and such manually - maybe I didn't need to worry about that? Sorry if this seems off-topic, but it quickly turned me off docs editing since I mostly write autoformatted code these days. Formatter would have to be a library and ideally run in CI to avoid messy diffs. Quick search pulled up: |
|
Hi @jcrben, Yes, I think ultimately we could. I also think that would make it easier to hack on them! I've been taking this one small step at a time. Hopefully auto-formatting is easy to do ... :) Some of our tags are whitespace sensitive, like program output. Let's see how xmlformat handlles it! |
|
OK so xmllint's --format does a bad job: -
-<para>You can disable IPv6 on a single interface using a normal sysctl (in thi
s
+ <para>You can disable IPv6 on a single interface using a normal sysctl (in t
his
example, we use interface <varname>eth0</varname>):
<programlisting>
boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
</programlisting>
</para>
-
-<para>As with IPv4 networking interfaces are automatically configured via
+ <para>As with IPv4 networking interfaces are automatically configured via
DHCPv6. You can configure an interface manually:Meanwhile, -<para>For configuring a gateway, optionally with explicitly specified interfac
e:
-
-<programlisting>
-networking.defaultGateway6 = {
- address = "fe00::1";
- interface = "enp0s3";
-}
-</programlisting>
-</para>
+ <para>For configuring a gateway, optionally with explicitly specified
+ interface:
+ <programlisting>networking.defaultGateway6 = { address = "fe00::1";
+ interface = "enp0s3"; }</programlisting></para>
|
|
Good news! -</para>
-
-<para>For configuring a gateway, optionally with explicitly specified interface:
-
+ </para>
+ <para>
+ For configuring a gateway, optionally with explicitly specified interface:
<programlisting>
networking.defaultGateway6 = {
address = "fe00::1";
interface = "enp0s3";
}
</programlisting>
-</para>
-
-<para>See <xref linkend='sec-ipv4' /> for similar examples and additional information.
-</para>
-
+ </para>
+ <para>
+ See <xref linkend='sec-ipv4' /> for similar examples and additional
+ information.
+ </para>
</section>
|
Motivation for this change
Make the docs easier to hack on with normal editors
Commits:
makein the nixos docsI: