aland/nixpkgs-odroid-hc4
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

uboot: (firmwareOdroidC2/C4) don't invoke patch tool, use patches = [] instead

Browse source 
https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/generic/setup.sh#L948
this can do it nicely.

Signed-off-by: Anton Arapov <anton@deadbeef.mx>
This commit is contained in:
Anton Arapov 2021-04-03 12:58:10 +02:00 • committed by Alan Daniels
commit 56de2bcd43
30691 changed files with 3076956 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

144
nixos/doc/manual/from_md/development/writing-documentation.chapter.xml Normal file
View file

@ -0,0 +1,144 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" 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>