| Code sample 1: Example of ocamlbuild plugin. |
hunk ./doc/argot.html 154
-In addition to the already available {b ...} (for bold),
-{i ...} (for italic), and {e ...} (for
-emphasized), Argot provides the following text formatting
-modifiers:
+In addition to the already available {b ...} (for bold), {i ...} (for italic), and {e ...} (for emphasized), Argot provides the following text formatting modifiers:
hunk ./doc/argot.html 177
-Token substitution allows one to use the value of either an
-environment variable or a command-line switch into an html page.
-This may for example be useful to insert insert the current date, or
-to specify the path of an element at documentation generation time:
+Token substitution allows one to use the value of either an environment variable or a command-line switch into an html page. This may for example be useful to insert insert the current date, or to specify the path of an element at documentation generation time:
hunk ./doc/argot.html 180
-The value of a token is first searched in -define id
-value switches passed to the ocamldoc tool, and then searched among the environment variables.
+The value of a token is first searched in -define id value switches passed to the ocamldoc tool, and then searched among the environment variables.
+
+Instead of passing multiple -define switches, it is also possible to load a bunch of definitions from a file through the -definitions file switch. Each line should have the following form: id=value, where the # character introduce comments (ending with the end of the line). Lines that do not conform to the given format are ignored.
+
+Finally, it is possible to refer to other variables when defining a new one (as long as this does not create a circular definition). As an example, the following file could be passed to the -definitions switch:
+
BASE=/path/to # prefix
+NAME=file
+FILE=$(BASE)/$(NAME).txt
+
hunk ./doc/argot.html 190
-It is possible to include images into the generated pages through
-{image path}. The image data will be directly
-embedded into the page using base64 format, in such a way that no
-external link remains in the generated html. There is thus no need
-to package the image along with the html pages.
+It is possible to include images into the generated pages through {image path}. The image data will be directly embedded into the page using base64 format, in such a way that no external link remains in the generated html. There is thus no need to package the image along with the html pages.
hunk ./doc/argot.html 192
-To avoid to use the full path to the image, it is possible to use the
-aforementioned token substitution inside the image formatter:
+To avoid to use the full path to the image, it is possible to use the aforementioned token substitution inside the image formatter:
hunk ./doc/argot.html 194
-Then, one has to specify the value for IMAGE_PATH on the
-command-line through the -define switch seen above:
+
Then, one has to specify the value for IMAGE_PATH on the command-line through the -define switch seen above:
hunk ./doc/argot.html 198
-When some explanation, albeit useful, is long and/or may appear as a
-digression, it is possible to fold it. It means that the texte inside
-a {fold digression} will appear as an ellipsis
-(i.e. ...) and will be unfolded (that is revealed) when the
-ellipsis will be clicked. At the opposite, clicking on the ellipsis while
-the foldable text is visible will make it disappear. Any formatting
-instruction can be used in the digression.
+When some explanation, albeit useful, is long and/or may appear as a digression, it is possible to fold it. It means that the texte inside a {fold digression} will appear as an ellipsis (i.e. ...) and will be unfolded (that is revealed) when the ellipsis will be clicked. At the opposite, clicking on the ellipsis while the foldable text is visible will make it disappear. Any formatting instruction can be used in the digression.
hunk ./doc/argot.html 200
-Argot also defines a bunch of new tags that can be used to enhance
-documentation. Some of these tags come with image icons; these have
-been designed by Mark James, released under the Creative Commons
-Attribution 2.5 License, and are available at
-http://www.famfamfam.com/lab/icons/silk/.
+Argot also defines a bunch of new tags that can be used to enhance documentation. Some of these tags come with image icons; these have been designed by Mark James, released under the Creative Commons Attribution 2.5 License, and are available at http://www.famfamfam.com/lab/icons/silk/.
hunk ./doc/argot.html 205
-@typevar, to document type variables in the same
-way @param is used for parameters;
-@copyright and @license to be used along
-with the @author parameter;
-@alias, @synonym, and
-@equivalent, to define synonyms or equivalences;
- @todo, or @unimplemented, to mark an
-implementation-in-progress;
-@todoc, or @docme, to mark a
-documentation-in-progress;
-@tofix, or @fixme, to mark a
-fix-in-progress;
- @stateful, to mark that a given function relies on
-a state;
-@threadsafe, to mark that a given function can be
-used in a multithread context;
-@threadsafe, to mark that a given function cannot be
-used in a multithread context;
- @attention, to introduce text by
-the
@typevar, to document type variables in the same way @param is used for parameters;
+@copyright and @license to be used along with the @author parameter;
+@alias, @synonym, and @equivalent, to define synonyms or equivalences;
+ @todo, or @unimplemented, to mark an implementation-in-progress;
+@todoc, or @docme, to mark a documentation-in-progress;
+@tofix, or @fixme, to mark a fix-in-progress;
+ @stateful, to mark that a given function relies on a state;
+@threadsafe, to mark that a given function can be used in a multithread context;
+@threadunsafe, to mark that a given function cannot be used in a multithread context;
+ @attention, to introduce text by the
@bug, to introduce text by
-the
@bug, to introduce text by the
@error, to introduce text by
-the
@error, to introduce text by the
@info, to introduce text by
-the
@info, to introduce text by the
@new, to introduce text by
-the
@new, to introduce text by the
@note, to introduce text by
-the
@note, to introduce text by the
@remark, to introduce text by
-the @remark, to introduce text by the @warning, to introduce text by
-the
@warning, to introduce text by the
+
+
+The @license tag will only print its argument if it does not recognize the license, but will create a link to the actual webpage of the license otherwise. The list of predefined licenses is the following (the recognition being case insensitive):
+
-
+gpl, gpl1, and gplv1 will point to http://www.gnu.org/licenses/old-licenses/gpl-1.0.html
+
- gpl2, and gplv2 will point to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+
- gpl3, and gplv3 will point to http://www.gnu.org/licenses/gpl.html
+
- lgpl, and lgplv2 will point to http://www.gnu.org/licenses/old-licenses/lgpl-2.0.html
+
- lgpl21, lgpl2.1, lgpl2_1, lgplv21, lgplv2.1, and lgplv2_1 will point to http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+
- lgpl3, and lgplv3 will point to http://www.gnu.org/licenses/lgpl.html
+
- agpl will point to http://www.gnu.org/licenses/agpl.html
+
- bsd will point to http://www.freebsd.org/copyright/license.html
+
- mit will point to http://www.opensource.org/licenses/mit-license.php
+
- apache will point to http://www.apache.org/licenses/
+
- qpl will point to http://doc.trolltech.com/3.0/license.html
+
- cecill, and cecill-a will point to http://www.cecill.info/licences/Licence_CeCILL_V2-en.html
+
- cecill-b will point to http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
+
- cecill-c will point to http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html
+
+Search
+Argot is able to embed search facilities into the generated pages when passed the -search command-line switch. The search window can then be opened by clicking on the magnifying glass (i.e.
) that appears on the index.html page as well as on each module page.
+The ability to open the search window from its icon, and to perform an actual search, needs JavaScript to be available and enabled on the browser used to consult the documentation.
+
+The search window is composed of two parts: the upper part allowing to select search criteria, and the lower part displaying results. Clicking on a search result will make the main window point to the clicked element.
+
+Three search modes are provided:
+
-
+search by exact name ;
+
- search by regular expression over names ;
+
- search by type.
+
+Search by name
can be made on simple names as well as on fully qualified names. Moreover, all names can be used : values, types, modules, constructors, etc.
+Search by regular expression
is akind to search by name except that all names matching the passed regular expression are returned. The regular expression should be written using the JavaScript syntax3. As an example, it is possible to retrieve all the elements starting with fold by using the following regular expression: fold.*.
+Search by type
allows to search for a value by giving its type. It is based on the ideas put forward by Roberto Di Cosmo (in particular the ocamlsearch tool for CamlLight). This means that the search does not retrieve values with exactly the same type, but with values whose types are isomorphic4. Practically this means that for example:
+
-
+int -> float -> int, float -> int -> int, and float * int -> int are isomorphic (because the differences are only in the way and order parameters are passed);
+
- string and unit -> string are isomorphic (because one always has a unit value at hand);
+
- ’from list -> (’from -> ’to) -> ’to list and (’a -> ’b) -> ’a list -> ’b list are isomorphic (because type variables can be renamed, and parameters reordered).
+
+As of version 1.0, type-based search is experimental and does not support the following features: objects, polymorphic variants, and labels.
hunk ./doc/argot.html 273
-