[latexrefman-commits] [SCM] latexrefman updated: r993 - trunk

[Vincent Belaiche]

Author: vincentb1
Date: 2021-08-21 15:28:07 +0000 (Sat, 21 Aug 2021)
New Revision: 993

Modified:
   trunk/writing.html
Log:
Provide guidlines about changing the structure.

For the sake of making the translation catch-up work easier...


Modified: trunk/writing.html
===================================================================
--- trunk/writing.html	2021-08-19 16:26:10 UTC (rev 992)
+++ trunk/writing.html	2021-08-21 15:28:07 UTC (rev 993)
@@ -284,9 +284,29 @@
     blocks of text to a uniform width.</li>
   <li><span class="listitem">Index</span>
     Use <code>@PkgIndex{..}</code> to add a package name to the index.
+  <li><span class="listitem">Structure</span>See next section
   </ul>
 
+<h3>Document structure</h3>
 
+<p>Here are a few points concerning how to change the document structure, if need be.</p>
+
+<ul>
+  <li><span class="listitem">Conservativeness</span>Don't change the document structure without prior discussion on the
+  mailing list. Changing the structure is a wider change that just modifying an existing entry or adding a new one.</li>
+  <li><span class="listitem">Backward compatibility</span>Please keep in mind that the document is exposed in a split
+  HTML with one page per node here: <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a>. So
+  every time you rename a node, you change the URL of the corresponding page and may break some link done by other
+  people to that page. To ensure backward compatibility, every time you do that create
+    an <code>@anchor{</code>…<code>} to the old name</code>.</li>
+  <li><span class="listitem">Elementary restructuring</span>Please keep in mind that the document is translated in
+  several languages. Do not make changes where both the node order is changed <i>and</i> the node content is changed. If
+  you do this, it becomes more difficult for the translators to track down what content change has happened. Do this
+  sort of evolution as two separate changes. If you don't have SVN access to the latexrefman repo, you can create a
+  local SVN or GIT repo, make the sequence of changes there, and then send the corresponding patch files. Or otherwise
+  make the changes as two separate contribution, and wait for the repo update between both.
+</ul>.
+
 <hr/>
 <div class='referenceinfo'> <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a></div>
 </body>