Comment author: administrator

Full_Name: Jean-Marc Eber
Version: 3.04+15
OS: linux
Submission from: parwch03-up2.sgib.com (207.45.248.23)

J'essaye ocamldoc3.04+15 (en gros le dernier cvs de travail dispo, plus
le reste du compilo bien-sûr).

3 choses:

Quand on définit un type et une valeur de même non, le fichier latex
généré comporte 2 ref de nom identiques, ce qui fait gueuler latex:

LaTex Warning: Label .... multiply defined.

En fait, alors même que sont bien gérés les espaces de noms différents
par module, ne le sont pas les espaces de nom par catégorie...

Il est impossible de "référencier" dans un même document un type
et une valeur de même nom, je pense.
J'ai ajouté des options dans ocamldoc pour pouvoir indiqué le préfixe à utiliser
pour les labels des values, types, exceptions, ...
Extrait du manuel ocamldoc :

-latex-value-prefix prefix
Give a prefix to use for the labels of the values in the generated LATEX document.
The default prefix is the empty string. You can also use the options
-latex-type-prefix,
-latex-exception-prefix,
-latex-module-prefix,
-latex-module-type-prefix,
-latex-class-prefix,
-latex-class-type-prefix,
-latex-attribute-prefix,
-latex-method-prefix.

These options are useful when you have, for example, a type and a value with
the same name. If you do not specify prefixes, LATEX will complain about multiply defined labels.

Je ne comprends pas bien les annotations de niveau de titre, par
exemple dans pervasives.mli. Pourquoi c'est passé au niveau 6 ?
Est-ce voulu ?
Oui. Comme la documentation générée par ocamldoc -latex est incluse
dans un autre document, il faut que les niveaux de titre correspondent.
J'ai donc utilisé les niveaux 6 et 7. Par la suite, j'ai ajouté des options
à ocamldoc pour pouvoir redéfinir le niveau de sectionnement associé aux niveaus de titres,
en laissant les niveaux 6 et 7. Ce n'est pas genant.

Le module LargeFile dans pervasives.mli semble faire problème à ocamldoc:
la table des matières est fichu, me semble-t-il, et à l'endroit du module
lui-même apparaît un [1.1] bizarre...
Moi il apparait numéroté avec 18.1.1, ce qui est normal puisque 18 est le
chapitre sur la 'core library', 18.1 le premier module de ce chapitre (et le seul),
et 18.1.1 le premier sous-module de Pervasives (et le seul).

--
Maxence

Comment author: administrator

J'essaye ocamldoc3.04+15 (en gros le dernier cvs de travail dispo, plus
le reste du compilo bien-sûr).

3 choses:

Quand on définit un type et une valeur de même non, le fichier latex
généré comporte 2 ref de nom identiques, ce qui fait gueuler latex:

LaTex Warning: Label .... multiply defined.

En fait, alors même que sont bien gérés les espaces de noms différents
par module, ne le sont pas les espaces de nom par catégorie...

Il est impossible de "référencier" dans un même document un type
et une valeur de même nom, je pense.
J'ai ajouté des options dans ocamldoc pour pouvoir indiqué le préfixe à
utiliser
pour les labels des values, types, exceptions, ...
Extrait du manuel ocamldoc :

-latex-value-prefix prefix
Give a prefix to use for the labels of the values in the generated
LATEX document.
The default prefix is the empty string. You can also use the options
-latex-type-prefix,
-latex-exception-prefix,
-latex-module-prefix,
-latex-module-type-prefix,
-latex-class-prefix,
-latex-class-type-prefix,
-latex-attribute-prefix,
-latex-method-prefix.

These options are useful when you have, for example, a type and a
value with
the same name. If you do not specify prefixes, LATEX will complain
about multiply defined labels.

Super. Je n'avais effectivement pas connaissance de ces options (je n'ai
pas encore le manuel).
Ca semble être effectivement exactement ce qu'il faut. Merci.

Quand tu "cross-"référencies, tu dois alors ajouter l'éventuel préfixe,
pour enlever l'ambiguité ?
Cette technologie est-elle réservée à latex, ou est-ce de même pour la doc
html (plus exactement pour
pouvoir ("cross"-)référencier à la fois des types et des valeurs par ex.) ?

Je ne comprends pas bien les annotations de niveau de titre, par
exemple dans pervasives.mli. Pourquoi c'est passé au niveau 6 ?
Est-ce voulu ?
Oui. Comme la documentation générée par ocamldoc -latex est incluse
dans un autre document, il faut que les niveaux de titre correspondent.
J'ai donc utilisé les niveaux 6 et 7. Par la suite, j'ai ajouté des
options
à ocamldoc pour pouvoir redéfinir le niveau de sectionnement associé aux
niveaus de titres,
en laissant les niveaux 6 et 7. Ce n'est pas genant.

Encore une fois, cela semble résoudre tous mes problèmes: je cheque et te
reviens éventuellement.

Le module LargeFile dans pervasives.mli semble faire problème à
ocamldoc:
la table des matières est fichu, me semble-t-il, et à l'endroit du
module
lui-même apparaît un [1.1] bizarre...
Moi il apparait numéroté avec 18.1.1, ce qui est normal puisque 18 est le
chapitre sur la 'core library', 18.1 le premier module de ce chapitre (et
le seul),
et 18.1.1 le premier sous-module de Pervasives (et le seul).

Je recheque et te préciserai... Je n'avais pas conscience du fait qu'un
(sous-)module
ocaml "drive" la hiérarchie latex... j'analyse un peu et te reviens.

Merci,

A bientôt,

Jean-Marc

Comment author: administrator

Super. Je n'avais effectivement pas connaissance de ces options (je n'ai
pas encore le manuel).
Ca semble être effectivement exactement ce qu'il faut. Merci.
Et pour cause, je viens de les ajouter :-)

Quand tu "cross-"référencies, tu dois alors ajouter l'éventuel préfixe,
pour enlever l'ambiguité ?
Cette technologie est-elle réservée à latex, ou est-ce de même pour la doc
html (plus exactement pour
pouvoir ("cross"-)référencier à la fois des types et des valeurs par ex.) ?
Il y a deux types de cross-ref différents:

• celui dans les commentaires ocamldoc,
• celui dans les documents incluants des documents générés par ocamldoc.

Dans le cross-ref dans les commentaires dans le source, on ne peut
pas choisir si on référence un type ou une value. Je considère qu'en
général l'un n'est pas très loin de l'autre, et surtout que c'est pas
forcément du bon style. Donc {!Toto.tutu} référence le type ou la valeur,
selon celui qui sera trouvé en premier par ocamldoc (normalement le
premier défini dans le fichier).

Par contre, dans les documents incluants des docs générés par ocamldoc,
on peut choisir ce que l'on peut référencer, en utilisant les labels
appropriés, différents pour les types et les valeurs si on a donné
des préfixes différents.

Amicalement,

Maxence