Since 0.6 Frugalware, all documentation is written in Asciidoc which means we have to write README.Frugalware files in Asciidoc syntax. Here are some basic Asciidoc features and some things you should and should not do a README.Frugalware.

1. Features

You can use *bold*, _italic_ and also `monospaced` fonts.

You can also ‘`quote’' if you want to do so.

When you want to add something to the

 ------------
 # root command line
 $ user command line
 > keyboard input
 ------------

that’s no problem at all.

Maybe you want bulleted items:

 .Items
 * item 1
 * item 2
 * here is number 3

And you can also create lists:

1. First
+
It's indented, belongs to first.
+
And this paragraph is also indented.

2. Second
+
This is inside the second point.
+
2.1. Foo
+
2.2. Bar
+
a. Baz

3. Third

End of list.

Some extras:

NOTE: You can also place notes.

TIP: It's a tip

WARNING: Warning.

IMPORTANT: This is important

CAUTION: Cave canem!

2. Restrictions

You must not underline titles with = or -. You might use ~, and ^ for subchapters. If you want one line titles place 3 or 4 = before the title and a space.

3. Skeleton for README.Frugalwares

Your titles should look similar to this:

 === First chapter

 --------------
 # pacman-g2 -Syu
 --------------

 === Second one

 `\_F_foobar`

 ==== This is a subchapter...

 ...and its contents.

or

 First chapter
 ~~~~~~~~~~~~~

 --------------
 # pacman-g2 -Syu
 --------------

 Second one
 ~~~~~~~~~~

 `\_F_foobar`

 This is a subchapter...
 ^^^^^^^^^^^^^^^^^^^^^^^

 ...and its contents.

4. Skeleton for standalone documentation

You might ask then: okay, but how do I start? Here is a really simple example:

 = Title
 Author Name <foo@frugalware.org>

 == First chapter

 --------------
 pacman-g2 -Syu
 --------------

 == Second one

 `\_F_foobar`

And you can generate the HTML using

asciidoc -a toc -a numbered skel.txt

The documentation should be placed under the /docs dir in the FST. Please add a link to it in index.txt and in index-user.txt or index-devel.txt depending on the type of the documentation.

5. Buiding it on your own machine

Install the tools necessary to build the documentation (if you haven’t already done so):

# pacman-g2 -S make asciidoc po4a

Get the necessary source code and translations:

$ mkdir ~/git
$ cd ~/git
$ git clone http://frugalware.org/git/pub/frugalware/frugalware-current current
$ git clone http://frugalware.org/git/pub/other/translations
$ cd current/docs

Generate additional documentation and update the po files from the translations repository:

$ make packages.txt user.txt po

Generate the localized documentation source from the po files:

$ po4a -k 0 po4a.cfg

Generate HTML from the source:

$ cd hu
$ asciidoc -a toc -a numbered -a sectids network.txt

Now you can look at the result of your translation in a web browser.

If you have already done this, and you updated the translation, you need to:

$ cd ~/git/translations
$ git pull --rebase
$ cd ~/git/current/docs
$ rm -rf po
$ make po
$ po4a -k 0 po4a.cfg
$ cd hu
$ asciidoc -a toc -a numbered -a sectids network.txt

and now you should be able to see your updated translation in the updated HTML.

6. Adding a new project to Pootle

Well, this happens rarely, and so is not well documented, but here is what is needed:

  • autogen.sh should support importing po files from the translations repository and should have a --pot-only switch. gnetconfig is a good example.

  • The pot file should be updated daily. Add the project’s autogen.sh to -current’s /tools/genpkgdbs.

  • Run the above command manually once.

  • Add the pot file to pootle-update in the pacman-tools repository.

  • Run pootle-update manually once.

  • Log in to Pootle with administrator rights and create a new project.

  • Add the necessary new languages on the web interface.

  • Translate a few strings for one language and commit.

  • Pull the translations repository locally and verify that you get the expected results.