= Frugalware Asciidoc quickstart Since 0.6 Frugalware documentation is written in asciidoc which means we have to write README.Frugalware files in asciidoc syntax. Here are some basic asciidoc features and also some things you should *not* do in a README.Frugalware. == 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 somes 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! ------------------------------- == 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. == Skeleton for README.Frugalwares So your titles should look something similar: -------------------------------- === 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. -------------------------------- == Skeleton for standalone documentations You might ask then: okay, but how to start? Here is a really simple example: -------------------------------- = Title Author Name == First chapter -------------- pacman-g2 -Syu -------------- == Second one `\_F_foobar` -------------------------------- And you can generate the html using ------------------------------------ asciidoc -a toc -a numbered skel.txt ------------------------------------ The documentations should be placed under the `/docs` dir in 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. == Buiding it on your own machine Install 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 git://git.frugalware.org/pub/frugalware/frugalware-current current $ git clone git://git.frugalware.org/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 already done this, and you updated the translation, you need: ---- $ cd ~/git/translations $ git pull $ 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. == Adding a new project to Pootle Well, this happens rarely, and thus a bit undocumented, but here is what 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.