kookie
/
nomicon
1
0
Fork 0
Code Issues Projects Releases 1 Activity

nixos: nixos/doc/manual/development/writing-documentation.xml to CommonMark

Browse Source
mullvad-ns
Bobby Rong 3 years ago
parent d80bde37a8
commit 1f3d513839
4 changed files with 238 additions and 151 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 2
      nixos/doc/manual/development/development.xml
  2. 93
      nixos/doc/manual/development/writing-documentation.chapter.md
  3. 150
      nixos/doc/manual/development/writing-documentation.xml
  4. 144
      nixos/doc/manual/from_md/development/writing-documentation.chapter.xml

2
nixos/doc/manual/development/development.xml
Unescape View File

@ -12,7 +12,7 @@
<xi:include href="../from_md/development/sources.chapter.xml" />
<xi:include href="writing-modules.xml" />
<xi:include href="../from_md/development/building-parts.chapter.xml" />
<xi:include href="writing-documentation.xml" />
<xi:include href="../from_md/development/writing-documentation.chapter.xml" />
<xi:include href="../from_md/development/building-nixos.chapter.xml" />
<xi:include href="nixos-tests.xml" />
<xi:include href="../from_md/development/testing-installer.chapter.xml" />

93
nixos/doc/manual/development/writing-documentation.chapter.md
Unescape View File

@ -0,0 +1,93 @@
# Writing NixOS Documentation {#sec-writing-documentation}
As NixOS grows, so too does the need for a catalogue and explanation of
its extensive functionality. Collecting pertinent information from
disparate sources and presenting it in an accessible style would be a
worthy contribution to the project.
## Building the Manual {#sec-writing-docs-building-the-manual}
The DocBook sources of the [](#book-nixos-manual) are in the
[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
subdirectory of the Nixpkgs repository.
You can quickly validate your edits with `make`:
```ShellSession
$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
nix-shell$ make
```
Once you are done making modifications to the manual, it\'s important to
build it before committing. You can do that as follows:
```ShellSession
nix-build nixos/release.nix -A manual.x86_64-linux
```
When this command successfully finishes, it will tell you where the
manual got generated. The HTML will be accessible through the `result`
symlink at `./result/share/doc/nixos/index.html`.
## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
For general information on how to write in DocBook, see [DocBook 5: The
Definitive Guide](http://www.docbook.org/tdg5/en/html/docbook.html).
Emacs nXML Mode is very helpful for editing DocBook XML because it
validates the document as you write, and precisely locates errors. To
use it, see [](#sec-emacs-docbook-xml).
[Pandoc](http://pandoc.org) can generate DocBook XML from a multitude of
formats, which makes a good starting point. Here is an example of Pandoc
invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:
```ShellSession
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
```
Pandoc can also quickly convert a single `section.xml` to HTML, which is
helpful when drafting.
Sometimes writing valid DocBook is simply too difficult. In this case,
submit your documentation updates in a [GitHub
Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
handle the conversion to XML for you.
## Creating a Topic {#sec-writing-docs-creating-a-topic}
You can use an existing topic as a basis for the new topic or create a
topic from scratch.
Keep the following guidelines in mind when you create and add a topic:
- The NixOS [`book`](http://www.docbook.org/tdg5/en/html/book.html)
element is in `nixos/doc/manual/manual.xml`. It includes several
[`parts`](http://www.docbook.org/tdg5/en/html/book.html) which are in
subdirectories.
- Store the topic file in the same directory as the `part` to which it
belongs. If your topic is about configuring a NixOS module, then the
XML file can be stored alongside the module definition `nix` file.
- If you include multiple words in the file name, separate the words
with a dash. For example: `ipv6-config.xml`.
- Make sure that the `xml:id` value is unique. You can use abbreviations
if the ID is too long. For example: `nixos-config`.
- Determine whether your topic is a chapter or a section. If you are
unsure, open an existing topic file and check whether the main
element is chapter or section.
## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
Open the parent XML file and add an `xi:include` element to the list of
chapters with the file name of the topic that you created. If you
created a `section`, you add the file to the `chapter` file. If you created
a `chapter`, you add the file to the `part` file.
If the topic is about configuring a NixOS module, it can be
automatically included in the manual by using the `meta.doc` attribute.
See [](#sec-meta-attributes) for an explanation.

150
nixos/doc/manual/development/writing-documentation.xml
Unescape View File

@ -1,150 +0,0 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-writing-documentation">
<title>Writing NixOS Documentation</title>
<para>
As NixOS grows, so too does the need for a catalogue and explanation of its
extensive functionality. Collecting pertinent information from disparate
sources and presenting it in an accessible style would be a worthy
contribution to the project.
</para>
<section xml:id="sec-writing-docs-building-the-manual">
<title>Building the Manual</title>
<para>
The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
subdirectory of the Nixpkgs repository.
</para>
<para>
You can quickly validate your edits with <command>make</command>:
</para>
<screen>
<prompt>$ </prompt>cd /path/to/nixpkgs/nixos/doc/manual
<prompt>$ </prompt>nix-shell
<prompt>nix-shell$ </prompt>make
</screen>
<para>
Once you are done making modifications to the manual, it's important to
build it before committing. You can do that as follows:
</para>
<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
<para>
When this command successfully finishes, it will tell you where the manual
got generated. The HTML will be accessible through the
<filename>result</filename> symlink at
<filename>./result/share/doc/nixos/index.html</filename>.
</para>
</section>
<section xml:id="sec-writing-docs-editing-docbook-xml">
<title>Editing DocBook XML</title>
<para>
For general information on how to write in DocBook, see
<link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook
5: The Definitive Guide</link>.
</para>
<para>
Emacs nXML Mode is very helpful for editing DocBook XML because it validates
the document as you write, and precisely locates errors. To use it, see
<xref linkend="sec-emacs-docbook-xml"/>.
</para>
<para>
<link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML
from a multitude of formats, which makes a good starting point.
<example xml:id="ex-pandoc-xml-conv">
<title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>
<screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>
</example>
Pandoc can also quickly convert a single <filename>section.xml</filename> to
HTML, which is helpful when drafting.
</para>
<para>
Sometimes writing valid DocBook is simply too difficult. In this case,
submit your documentation updates in a
<link
xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
Issue</link> and someone will handle the conversion to XML for you.
</para>
</section>
<section xml:id="sec-writing-docs-creating-a-topic">
<title>Creating a Topic</title>
<para>
You can use an existing topic as a basis for the new topic or create a topic
from scratch.
</para>
<para>
Keep the following guidelines in mind when you create and add a topic:
<itemizedlist>
<listitem>
<para>
The NixOS
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>
element is in <filename>nixos/doc/manual/manual.xml</filename>. It
includes several
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>
which are in subdirectories.
</para>
</listitem>
<listitem>
<para>
Store the topic file in the same directory as the <tag>part</tag> to
which it belongs. If your topic is about configuring a NixOS module, then
the XML file can be stored alongside the module definition
<filename>nix</filename> file.
</para>
</listitem>
<listitem>
<para>
If you include multiple words in the file name, separate the words with a
dash. For example: <filename>ipv6-config.xml</filename>.
</para>
</listitem>
<listitem>
<para>
Make sure that the <tag>xml:id</tag> value is unique. You can use
abbreviations if the ID is too long. For example:
<varname>nixos-config</varname>.
</para>
</listitem>
<listitem>
<para>
Determine whether your topic is a chapter or a section. If you are
unsure, open an existing topic file and check whether the main element is
chapter or section.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="sec-writing-docs-adding-a-topic">
<title>Adding a Topic to the Book</title>
<para>
Open the parent XML file and add an <varname>xi:include</varname> element to
the list of chapters with the file name of the topic that you created. If
you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>
file. If you created a <tag>chapter</tag>, you add the file to the
<tag>part</tag> file.
</para>
<para>
If the topic is about configuring a NixOS module, it can be automatically
included in the manual by using the <varname>meta.doc</varname> attribute.
See <xref
linkend="sec-meta-attributes"/> for an explanation.
</para>
</section>
</chapter>

144
nixos/doc/manual/from_md/development/writing-documentation.chapter.xml
Unescape View File

@ -0,0 +1,144 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-documentation">
<title>Writing NixOS Documentation</title>
<para>
As NixOS grows, so too does the need for a catalogue and explanation
of its extensive functionality. Collecting pertinent information
from disparate sources and presenting it in an accessible style
would be a worthy contribution to the project.
</para>
<section xml:id="sec-writing-docs-building-the-manual">
<title>Building the Manual</title>
<para>
The DocBook sources of the <xref linkend="book-nixos-manual" />
are in the
<link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><literal>nixos/doc/manual</literal></link>
subdirectory of the Nixpkgs repository.
</para>
<para>
You can quickly validate your edits with <literal>make</literal>:
</para>
<programlisting>
$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
nix-shell$ make
</programlisting>
<para>
Once you are done making modifications to the manual, it's
important to build it before committing. You can do that as
follows:
</para>
<programlisting>
nix-build nixos/release.nix -A manual.x86_64-linux
</programlisting>
<para>
When this command successfully finishes, it will tell you where
the manual got generated. The HTML will be accessible through the
<literal>result</literal> symlink at
<literal>./result/share/doc/nixos/index.html</literal>.
</para>
</section>
<section xml:id="sec-writing-docs-editing-docbook-xml">
<title>Editing DocBook XML</title>
<para>
For general information on how to write in DocBook, see
<link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
5: The Definitive Guide</link>.
</para>
<para>
Emacs nXML Mode is very helpful for editing DocBook XML because it
validates the document as you write, and precisely locates errors.
To use it, see <xref linkend="sec-emacs-docbook-xml" />.
</para>
<para>
<link xlink:href="http://pandoc.org">Pandoc</link> can generate
DocBook XML from a multitude of formats, which makes a good
starting point. Here is an example of Pandoc invocation to convert
GitHub-Flavoured MarkDown to DocBook 5 XML:
</para>
<programlisting>
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
</programlisting>
<para>
Pandoc can also quickly convert a single
<literal>section.xml</literal> to HTML, which is helpful when
drafting.
</para>
<para>
Sometimes writing valid DocBook is simply too difficult. In this
case, submit your documentation updates in a
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub
Issue</link> and someone will handle the conversion to XML for
you.
</para>
</section>
<section xml:id="sec-writing-docs-creating-a-topic">
<title>Creating a Topic</title>
<para>
You can use an existing topic as a basis for the new topic or
create a topic from scratch.
</para>
<para>
Keep the following guidelines in mind when you create and add a
topic:
</para>
<itemizedlist>
<listitem>
<para>
The NixOS
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>book</literal></link>
element is in <literal>nixos/doc/manual/manual.xml</literal>.
It includes several
<link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><literal>parts</literal></link>
which are in subdirectories.
</para>
</listitem>
<listitem>
<para>
Store the topic file in the same directory as the
<literal>part</literal> to which it belongs. If your topic is
about configuring a NixOS module, then the XML file can be
stored alongside the module definition <literal>nix</literal>
file.
</para>
</listitem>
<listitem>
<para>
If you include multiple words in the file name, separate the
words with a dash. For example:
<literal>ipv6-config.xml</literal>.
</para>
</listitem>
<listitem>
<para>
Make sure that the <literal>xml:id</literal> value is unique.
You can use abbreviations if the ID is too long. For example:
<literal>nixos-config</literal>.
</para>
</listitem>
<listitem>
<para>
Determine whether your topic is a chapter or a section. If you
are unsure, open an existing topic file and check whether the
main element is chapter or section.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="sec-writing-docs-adding-a-topic">
<title>Adding a Topic to the Book</title>
<para>
Open the parent XML file and add an <literal>xi:include</literal>
element to the list of chapters with the file name of the topic
that you created. If you created a <literal>section</literal>, you
add the file to the <literal>chapter</literal> file. If you
created a <literal>chapter</literal>, you add the file to the
<literal>part</literal> file.
</para>
<para>
If the topic is about configuring a NixOS module, it can be
automatically included in the manual by using the
<literal>meta.doc</literal> attribute. See
<xref linkend="sec-meta-attributes" /> for an explanation.
</para>
</section>
</chapter>
Write Preview
Loading…
Cancel
Save