lib/examples/README.new_examples

   1 DIRECTORY STRUCTURE & FILE NAMING
   2 ==================================
   3
   4 The examples directory has the following structure
   5
   6 examples/[language/]category/[subcategory]
   7
   8 Please use the layout category (with identical spelling to assure translation)
   9 as category subdirectory (e.g., "Letters"). See \DeclareCategory entry of the
  10 layout which corresponds to your example. Note the handling of special characters
  11 below.
  12
  13 If your example consists of one file only, and if there are no further examples
  14 relating to your layout yet, use the layout name, as defined in \DeclareLaTeXClass,
  15 as file name. In any case, use a verbose, transparent name (do not use insider acronyms
  16 as file names). Note the handling of special characters below.
  17
  18 If your example consists of multiple files, use an additional subdirectory.
  19 Use the layout name, as defined in \DeclareLaTeXClass, as subcategory subfolder
  20 name. Give the files verbose, transparent names that clarify the function of the respective
  21 file in the examples bundle. Note the handling of special characters below.
  22
  23 The optional language subdirectory that immediately follows examples/ uses the
  24 language code (e.g., 'de' for German). Use this if you provide a translation of
  25 an existing English example.
  26 The language subdirectory expands to the same subfolders than the English version
  27 and uses the same [English) filename (e.g., examples/Letters/myletter.lyx >
  28 examples/fr/Letters/myletter.lyx).
  29
  30
  31 NB: SPECIAL CHARACTERS IN FILE AND DIRECTORY NAMES:
  32 ===================================================
  33
  34 The following characters in file and directory names must be substituted, since they break
  35 LyX building with autotools:
  36
  37 * Blanks by '_' (e.g., My_Layout.lyx)
  38 * Parentheses by %28 and %29 (e.g., My_Layout_%28v._1%29.lyx)
  39 * Apersands by %26 (e.g., Journal_of_This_%26_That.lyx)
  40
  41 The substitution characters will be replaced again for LyX for translation and GUI display.
  42
  43
  44 THINGS TO CHECK BEFORE COMMITTING:
  45 ==================================
  46
  47 New files must be added to Makefile.am. If you add a new (sub)folder, you must also create a new category
  48 in Makefile.am (cf. dehandoutexamplesdir and dist_phdthesistemplates_DATA as example).
  49
  50 Please make sure before you commit (in a text editor) that the example that the file has the correct
  51 \origin specification. It should begin with /systemlyxdir/ and then point towards the subdirectory
  52 your file is in, e.g.
  53 \origin /systemlyxdir/templates/es/Presentations/
  54 This is particularly important if your file includes other files (such as graphics, bibliographies,
  55 children).
  56