= Frugalware Asciidoc quickstart 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. == 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! ------------------------------- == 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 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. -------------------------------- == Skeleton for standalone documentation You might ask then: okay, but how do I 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 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. == 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. == 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.