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



               <!doctype linuxdoc system>
               <article>
               <title>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