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.