Documentation FAQ
From Mandriva Community Wiki
Contents |
[edit] Installing from CD/DVD and updating to Cooker
You need to "update" your install to Cooker, to have latest features/UI to document Mandriva Linux. After installing from CD/DVD of Alpha/Beta/RC, proceed as follows:
- Login, su to become root and run edit-urpm-sources.pl
- Remove the checkmarks from existing media, then click Add and select a mirror to add all package sources
- Click OK once the sources are added
- Run urpmi --auto --auto-select to automatically upgrade all packages
- Reboot and you should have the "latest and greatest"
Notes:
- Needless to say, all this is NOT meant to be performed on a production machine
- Due to the very nature of Cooker, you may end up with a broken system after doing this, use at your own risk
- It is convenient to run urpmi.update -a && urpmi --auto --auto-select from time to time to have all the latest Cooker packages installed
[edit] Switch the Free theme to the PowerPack one
The PowerPack theme must be used to do screenshots. To switch the Free theme to the PowerPack one, proceed as follows:
- Remove the "Upgrade to PowerPack" icon from the desktop, or any other
"non-PowerPack" icon possible present on the desktop.
- Run rpmdrake (as root) and select the following packages (and possible dependencies):
mandriva-release-Powerpack mandriva-theme-Powerpack mandriva-theme-Powerpack-screensaver powerpack-kde*-config
- Apply and accept to install required software.
- Then deselect (mark for removal) the following packages (and possible dependencies):
free-kde*-config mandriva-theme-Free mandriva-theme-Free-screensaver mandriva-release-Free
- Apply and accept to remove software.
- On a terminal window, delete the ~/.kde and/or ~/.kde4 folders to recreate the userspace 'as new'. Please note that this will erase settings and may erase data for KDE applications.
- Reboot your Cooker machine and enjoy the "PowerPack"!
[edit] Manually Validate XML Modules before Committing
If you don't use a validating XML editor such as XXE, you are encouraged to validate your files before committing them to the repository.
Note that even if you don't validate the files it shouldn't break the whole repository since the compilation system ignores invalid files. Also, the svnnav utility shows invalid files and provides an error list in the module page.
So to manually validate your local files:
- get the XML DocBook schema: "wget http://www.docbook.org/xml/5.0/rng/docbookxi.rng"
- validate your file using the relaxng method described here: http://www.docbook.org/docs/howto/#validators
Note: you might get errors like this:
- "drakconsole" is referenced by an IDREF, but not defined.
This is because we reference (xref) IDs that are in another module and thus unreachable to the validator. Just ignore.
[edit] Using PO to translate docs
The doc team decided long ago to use XML to translate docs (TODO: Add short summary of reasons and pros and cons of XML vs. PO). We acknowledge that lots of translators, coming from the software translation (both GUI and CLI) world, are used to the PO (gettext) format and tools. We include this chat excerpt (thanks reinouts and the gnome-doc ppl!) in the hope that translators used to PO can translate our XML docs with the PO tools and format they are used to.
<claude> reinouts: the base configuration for doc xml could be seen here: <claude> http://live.gnome.org/GnomeDocUtilsCreateNew <reinouts> then its a matter to call xml2po to create a pot <claude> reinouts: and xml2po -e -u ll.po ../C/orig.xml to generate the translated doc reinouts: you can also see the functions doc_l10n_stats and generate_translated_docs in /damned-lies/trunk/update-stats.py to see how this can be automated <reinouts> (that's a reference to http://svn.gnome.org/viewvc/damned-lies/trunk/update-stats.py?revision=885&view=markup)
Note: please note that the GnomeDocUtilsCreateNew URL assumes the translation is being added to a gnome application, you'll have to adapt the instructions for the Mandriva Linux docs.
TODO: Clean this up with instructions more clear for mdv docs.
[edit] Icons
Throughout the doc we use icons for the software we document. There's been always problems as to where those icons lie, and authors have had to resort to things like asking (and bothering) the developers and even taking a screenshot and manipulating it to get the desired icon. This is not only time consuming, but also duplicates work and does not always lead to 'nice' icon images. See below for a quick guide on where to find icons to include in docs.
| Where do I find icons for... | In... | And possibily also in ... |
|---|---|---|
| MCC (Control Center) | /usr/share/mcc/themes/default/ | /usr/lib/libDrakX/icons/ |
| KDE software | /usr/share/icons/default.kde4/ | |
| GNOME software | /usr/share/pixmaps/ |
Remember that icons should:
- be preferably 48x48 pixels in size
- have a white background instead of a transparent background (which is known to affect PDF rendering, giving us black backgrounds in PDF output)
- be preferably named the same as the original when copying it over to common/images/
[edit] Replace a screenshot in a SVG
This procedure is to be used by both writers updating a module and translators
- open the SVG and note the PNG image name (right clic -> Image Properties)
- take the new screenshot, if possible using the same image size
- replace the PNG file on SVN withe the new screenshot
- delete the screenshot from the SVG in inkscape to avoid the image to be distorted if it has a different size
- import the new PNG in inkscape
- adjust the schema if necessary (push screenshot in background, adjust arrows, etc.)
