Refactoring

[lyx.git] / lib / templates / README.new_templates

diff --git a/lib/templates/README.new_templates b/lib/templates/README.new_templates
index 658d6b4d526b1145a8853e1b375fbea3fa7e99db..62cb4ca6d022a220ed380ca3f6632bb32ad24479 100644 (file)
--- a/lib/templates/README.new_templates
+++ b/lib/templates/README.new_templates
@@ -46,18 +46,18 @@ templates/[language/]category/[subcategory]
 
 Please use the layout category (with identical spelling to assure translation)
 as category subdirectory (e.g., "Letters"). See \DeclareCategory entry of the
-layout which corresponds to your template. Substitute blanks by '_'.
+layout which corresponds to your template. Note the handling of special characters
+below.
 
 If your template consists of one file only, and if there are no further templates
 relating to your layout yet, use the layout name, as defined in \DeclareLaTeXClass,
-as file name. Substitute blanks by '_' (e.g., My_Layout.lyx). In any case, use
-a verbose, transparent name (do not use insider acronyms as file names).
+as file name. In any case, use a verbose, transparent name (do not use insider
+acronyms as file names). Note the handling of special characters below.
 
 If your template consists of multiple files, use an additional subdirectory.
 Use the layout name, as defined in \DeclareLaTeXClass, as subcategory subfolder
-name. Substitute blanks by '_' (e.g., My_Layout). Give the files verbose,
-transparent names that clarify the function of the respective file in the templates
-bundle. Use '_' instead of blanks.
+name. Give the files verbose, transparent names that clarify the function of the
+respective file in the templates bundle. Note the handling of special characters below.
 
 The optional language subdirectory that immediately follows templates/ uses the
 language code (e.g., 'de' for German). Use this if you provide a translation of
@@ -66,5 +66,31 @@ The language subdirectory expands to the same subfolders than the English versio
 and uses the same [English) filename (e.g., templates/Letters/myletter.lyx > 
 templates/fr/Letters/myletter.lyx).
 
-If you add a new (sub)folder, you must create a new entry in Makefile.am.
+
+NB: SPECIAL CHARACTERS IN FILE AND DIRECTORY NAMES:
+===================================================
+
+The following characters in file and directory names must be substituted, since they break
+LyX building with autotools:
+
+* Blanks by '_' (e.g., My_Layout.lyx)
+* Parentheses by %28 and %29 (e.g., My_Layout_%28v._1%29.lyx)
+* Apersands by %26 (e.g., Journal_of_This_%26_That.lyx)
+
+The substitution characters will be replaced again for LyX for translation and GUI display.
+
+
+THINGS TO CHECK BEFORE COMMITTING:
+==================================
+
+New files must be added to Makefile.am. If you add a new (sub)folder, you must also create a new category
+in Makefile.am (cf. phdthesistemplatesdir and dist_dehandoutexamples_DATA as example). 
+
+Please make sure before you commit (in a text editor) that the example that the file has the correct
+\origin specification. It should begin with /systemlyxdir/ and then point towards the subdirectory
+your file is in, e.g.
+\origin /systemlyxdir/templates/es/Presentations/
+This is particularly important if your file includes other files (such as graphics, bibliographies,
+children).
+