5. Resuming automatic conversion#

This section lists known conversion errors and indicates the method to follow to correct them.

The odt docs were less WYSIWYG than they seemed and more What You See Is A Very Small Part Of What You Get! Indeed, after years of successive modifications, numerous blocks of text have superimposed successive layouts. For example, changing the font on the same word done in two stages (which already caused split words in ODT). The automatic conversion has therefore « cleaned up » this type of formatting with sometimes some blemishes.

Courier New font text boxes represented syntax. Since the text is not typed, the lines/paragraphs are not linked together, the conversion often divided these paragraphs into several blocks…

5.1. Accessibility#

Problem under analysis: When the page is not large enough, some documents (from Validation or salome_meca) are no longer accessible through the menus. Beyond a certain limit (on mobile for example), the menus disappear.

Solution: Access the list of documents by manual from the home page.

5.2. Fix syntax blocks#

note

The paragraph in the u4/u7 documents is now generated automatically. See Automatic generation.

Example:

Source/manuals/man_d/d9/d9/d9.02.02/les_impressions.rst:129: ERROR: Undefined substitution referenced: "G".

In the document, we can see that line 129 corresponds to:

* the name of the object (possibly supplemented by the collector's item number).

|G| 0| 1| -2| 69888784|U| 11| D| ________GLOBAL ________$$CARA

In RST, |G| corresponds to the substitution of G. Here, simply declare that it is a block of plain text:

* the name of the object (possibly supplemented by the collector's item number).

.. code-block:: text

    |G| 0| 1| -2| 69888784|U| 11| D| ________GLOBAL ________$$CARA
notes

.. code-block:: python: Have a complete block extracted from a command file is rarely a very good idea (hard to keep it up to date). But in this case, you can use Python coloring to render the block.

.. code-block:: text: For plain text, specify it as follows.

5.3. Correction of tables#

The format of the tables chosen by the automatic conversion is the most flexible but too complicated to maintain!

Example:

Special case of equality (or non-equality) criteria for "floating" numbers:

+---------+------------------------------------------------------------------------------------+
| ‘EGAL’  | égalité "exacte" des 2 nombres flottants                                           |
+---------+------------------------------------------------------------------------------------+
| ‘ABSO’  | égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue :   |
|         | vrai si |x1-x2| < eps                                                         |
+---------+------------------------------------------------------------------------------------+
| ‘RELA’  | égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative :  |
|         | vrai si |x1-x2| < eps * |x1|                                              |
+---------+------------------------------------------------------------------------------------+

Here, there would be two errors:

  • the misalignment of the characters | at the end of the table row,

  • and the wrong substitution (previous paragraph but in a different context).

source/manuals/man_d/d8/d8/d8.00.01/conversion.rst:79: ERROR: Malformed table.
source/manuals/man_d/d8/d8/d8.00.01/conversion.rst:85: ERROR: Undefined substitution referenced: "x1-x2".

It is preferable to use a simpler format (csv):

.csv-table:

    'EGAL', "exact" equality of the 2 floating numbers
    'ABSO', equality of the 2 floating numbers to within one epsilon (eps) in absolute comparison: true if:math: `|x1-x2| < eps`
    'RELA', equality of the 2 floating numbers to within one epsilon (eps) in relative comparison: true if:math: `|x1-x2| < eps * |x1|`

This results in:

note

Is the chart really the ideal form to provide information? Isn’t a list just as readable?

Special case of equality (or non-equality) criteria for « floating » numbers:

  • “EGAL”: « exact » equality of the 2 floating numbers

  • “ABSO”: equality of the 2 floating numbers to within one epsilon (eps) in absolute comparison: true if:math: |x1-x2| < eps

  • “RELA”: equality of the 2 floating numbers to within one epsilon (eps) in relative comparison: true if:math: |x1-x2| < eps * |x1|

with:

- 'EGAL': "exact" equality of the 2 floating numbers
- 'ABSO': equality of the 2 floating numbers to within one epsilon (eps) in absolute comparison: true if:math: `|x1-x2| < eps`
- 'RELA': equality of the 2 floating numbers to within one epsilon (eps) in relative comparison: true if:math: `|x1-x2| < eps * |x1|`