Translating Linuxconf help screens: quick start Introduction 11.. TTeecchhnnoollooggyy uusseedd ttoo wwrriittee tthhee hheellppss All the help files are written in the SGML variant used by the LDP team (Linux Documentation Project). They use it for HOWTOs especially. You can find more information about linuxdoc-sgml at http://what_is_the_official_site_for_it This format is especially convenient because it allows one to write help files which can be translated in HTML and ASCII text. Further, linuxdoc-sgml support accentuated characters, making it nice for foreign languages. The output looks good in pure text and it is expected that the output will be appealing when the graphical (GUI) version of Linuxconf will be available. If you are not familiar with _l_i_n_u_x_d_o_c_-_S_G_M_L, you can still patch the *.help file and send me the modification. I will incorporate them in the SGML. Just remember that the files with the extension sgml are the originals: The corresponding html and help files are generated from them. 22.. AAbboouutt mmaakkee cclleeaann Since most people do not have the Linuxdoc package, "make clean" does not remove the *.help files nor the *.html. So you don't need to have the linuxdoc package to compile Linuxconf. You need it only to modify help screens. 33.. AA qquuiicckk ssttaarrtt First of all, you might be interested in translating the help files or simply completing the work. Use the command linuxconf --helpfile It will show all the help files needed by Linuxconf. Lines starting with _*_*_* indicate that the help files are missing (Not done). 33..11.. PPrreeppaarriinngg aa ttrraannssllaattiioonn The original English help files are located in the directory help.files/sources. There is one subdirectory per source directory (corresponding to the major components of Linuxconf: networking, mail, dns, file systems, etc...). 33..11..11.. SSeettttiinngg tthhee ddiirreeccttoorryy ssttrruuccttuurree Use the script help.files/scripts/inithelplang.sh to install a new directory hierarchy in the help.files directory. There will be one directory per language. Use the same language ID as used to translate the messages (fr for French for example). Pass this ID as the argument to inithelplang.sh. You must execute this script from the help.files directory. This will create a subdirectory named following the language ID. A bunch of subdirectories will have been created with few files in it. 33..11..22.. RReeffrreesshhiinngg tthhee ddiirreeccttoorryy ssttrruuccttuurree The script help.files/scripts/inithelplang.sh may be used after the directory hierarchy has been created. It will make sure that all new directories in help.files/sources are created and initialised. Running this script twice does not make any arm. 33..11..33.. LLiisstt ooff ffiilleess ttoo ttrraannssllaattee Visit each subdirectory of the newly create directory and execute the _m_a_k_e command without argument. This will list all help files not translated. For each missing help file, retrieve the original from the sources directory and go for it. For example, if you wish to translate the help screen routes.sgml in the netconf directory, execute cp ../../sources/netconf/routes.sgml . 33..22.. FFoorrmmaattttiinngg tthhee SSGGMMLL ffiilleess Once you have one (or more :-) ) help file done (or partially done) you may wish to format it and check it out from Linuxconf. Simply run the _m_a_k_e command without argument. It will format any SGML files not formatted yet or which have changed. If no errors are detected, you can run "make install" from the subdirectory holding the SGML file. You must be root to install help files. Once installed, you can run Linuxconf and access the help file from the appropriate dialog. Make sure you have switched Linuxconf to the proper language. 33..33.. IInnssttaalllliinngg aallll hheellpp ffiilleess You can run the _m_a_k_e _i_n_s_t_a_l_l command from the help.files directory. This will install all help files (.html and .help) for all language in the /usr/lib/linuxconf directory. 44.. SSeennddiinngg tthhee rreessuulltt ttoo tthhee aauutthhoorr Once you have a suitable amount of help file translated (maybe just the first one main/intro.sgml), send it to me (jacques@solucorp.qc.ca). Send me a tar file of the complete language directory and I will include it in the source distribution of Linuxconf. Don't count on me to spell check your work though :-) 55.. AAnn iinnttrroodduuccttiioonn ttoo lliinnuuxxddoocc--ssggmmll _L_i_n_u_x_d_o_c_-_s_g_m_l is evolving with new features. Linuxconf use a subset of them so learning how to write help file is simple. 55..11.. TThhee hheeaaddiinngg Each help file start with the following lines
Some title <author>Introduction I use the author field to store the sub-title. Looks good. So you copy that and you change the title and subtitle. 55..22.. TThhee aabbssttrraacctt You may want to introduce the general idea about the topic in a short paragraph. You do this this way. <abstract> Linuxconf is great, yet some help files are missing. Here is your chance to be a hero. </abstract> The abstract section is optional. 55..33.. TThhee sseeccttiioonnss The keyword _s_e_c_t, _s_e_c_t_1 _s_e_c_t_2 etc... are used to start a section and provide its title. No need for a </sect> like _H_T_M_L. You need to enter a <p> Further, sect sect1 sect2 must be properly match. You can't jump from a sect to a sect2 without a sect1 somewhere in the middle, unlike HTML which lets you put h1 h2 in any order. the sect verb really means a heading (section title). Here is a short document <sect>what is Linuxconf <p> bla bla bla <sect1>When did it started ? <p> bla bla bla <sect1>Is it expected to end ? <p> bla bla bla <sect>Licensing <p> bla bla bla 55..44.. PPaarraaggrraapphhss Paragraphs are implied by an empty line. No need to the <p> everywhere like in HTML. 55..55.. PPrreesseennttaattiioonn ccoonnttrroollss _l_i_n_u_x_d_o_c_-_s_g_m_l has few mechanism to control the look of some part of the document. This is somewhat limited. Remember that the goal is to produce documents readable on a text console and in HTML (linuxdoc- sgml can also translate to _L_a_T_e_X, producing a very nice looking document). 55..55..11.. LLiissttss 55..55..11..11.. BBuulllleett lliissttss List are controlled by the itemize and item keywords. Here is an example. Linuxconf features are: <itemize> <item>Networking <item>DNS management </itemize> 55..55..22.. EEmmpphhaassiiss The keyword em is used to high-lit some part of the document generally a word. You can use both the long and short form to quote something. For example <em/Linuxconf/ is <em>great</em>. 55..55..33.. TTyyppeewwrriitteerr ((ssccrreeeenn)) ffoonnttss The tscreen keyword force the selection of a non proportional fonts where it applies. You can use the short and long form. It is generally used (in Linuxconf help files at least) in combination with the verb keyword. See below. 55..55..44.. PPrree ffoorrmmaatttteedd tteexxtt The verb keyword is used to suppress the formating done by the various tools in linuxdoc-sgml. You use this either to disable the parsing of linuxdoc-sgml or to present Linux commands. For example, here is some C source code int main (int argc, char *argv[]) { for (i=0; i<10; i++){ printf ("hello\n"); } } 55..55..55.. UUrrll You can specify urls (www pointers) that will be effective in the HTML version of the help screen. This is done using the htmlurl command: <htmlurl url="http://server/path" name="text to present" > 66.. TTrraannssllaattiinngg hheellpp ffiilleess aanndd ttrraacckkiinngg tthhee cchhaannggeess Currently, the easiest way to track the change to the help file is by doing a diff of the help.files/sources directory between two releases of linuxconf. When starting a translation, one quick way to find which help file are not translated yet is by using the scripts/chknewhelp.sh. This scripts used a single argument, which is the id of the language. For example, for the french translation, the following command walks you directory per directory and shows what has to be done. scripts/chknewhelp.sh fr