Refactoring

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

diff --git a/lib/templates/README.new_templates b/lib/templates/README.new_templates
index 9118a9fcb0b25bac4ec324bbe275225bebe567c9..62cb4ca6d022a220ed380ca3f6632bb32ad24479 100644 (file)
--- a/lib/templates/README.new_templates
+++ b/lib/templates/README.new_templates
@@ -11,18 +11,18 @@ LyX stores some properties in a file, for example:
         \inputencoding default
         \fontscheme default
         \epsfig dvips
-        \papersize a4paper 
-        \paperfontsize 12 
-        \baselinestretch 1.00 
-        \secnumdepth 3 
-        \tocdepth 3 
-        \paragraph_separation skip 
-        \quotes_language german 
-        \quotes_times 2 
-        \paperorientation portrait 
-        \papercolumns 9 
-        \papersides 1 
-        \paperpagestyle plain 
+        \papersize a4paper
+        \paperfontsize 12
+        \baselinestretch 1.00
+        \secnumdepth 3
+        \tocdepth 3
+        \paragraph_separation skip
+        \quotes_language german
+        \quotes_times 2
+        \paperorientation portrait
+        \papercolumns 9
+        \papersides 1
+        \paperpagestyle plain
 
 Some of these may be very reasonable for a certain template. In the
 case of a dinbrief-template this might be the papersize, the language
@@ -36,3 +36,61 @@ text editor (for example ed, ex or vi) that you don't want to set
 explicit for this template. LyX will use the user's default-values
 (defined in lyxrc) if a property isn't defined in the file itself.
 
+
+DIRECTORY STRUCTURE & FILE NAMING
+==================================
+
+The templates directory has the following structure
+
+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. 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. 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. 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
+an existing English template.
+The language subdirectory expands to the same subfolders than the English version
+and uses the same [English) filename (e.g., templates/Letters/myletter.lyx > 
+templates/fr/Letters/myletter.lyx).
+
+
+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).
+
+