jon.recoil.org
this repo has no description
Line editing interface.mld (#1182)
* mostly formatting
* fix typo
Co-authored-by: panglesd <peada@free.fr>
* changed correct to correctly for accuracy
---------
Co-authored-by: panglesd <peada@free.fr>
authored by
Christine Rose
panglesd
and committed by
GitHub
160931f4
468ab028
+12
-12
doc/interface.mld
+12
-12
doc/interface.mld
···
1
-
{0 [odoc] interface guarantees}
2
3
[odoc] has several 'public facing' parts with varying levels of support guarantees.
4
This document describes what those interfaces are, what the support levels are
···
6
7
{2 Documentation Comments}
8
9
-
The first and most important is the syntax of the documentation comments present in source code.
10
This is relevant to everyone who is writing code that’s intended to be documented by [odoc], so it applies to the widest set of people.
11
We have a separate page describing the {{!page-ocamldoc_differences}markup differences from OCamldoc}.
12
13
{2 CLI Interface}
14
15
-
The way in which the [odoc] CLI is invoked is not trivial, and it requires careful
16
-
ordering and correct arguments to produce correctly linked documentation. It’s not expected that
17
-
end-users will invoke [odoc] by hand, but rather it will be driven by separate tools. As a consequence, it’s important to preserve the tools’ ability to create good documentation with
18
-
each release of [odoc], so we’ll ensure backward compatibility of the CLI as much as possible.
19
There are currently three ‘first class’ tools that 'drive' [odoc]. We will not make
20
releases of [odoc] whilst knowingly breaking these tools. These are:
21
···
23
- Dune
24
- OCaml
25
26
-
Here, OCaml refers to the newly merged configure option (from 4.12.0) that builds the standard library documentation with
27
-
[odoc]. If the recommended way of invoking [odoc] changes, we will work with the maintainers of these projects
28
-
to ensure they are updated correspondingly.
29
30
Additionally, there will be a reference implementation of a tool to build [odoc]'s documentation, which should
31
serve as a guide for anyone building other 'drivers' of [odoc].
···
33
{2 Output Formats}
34
35
[odoc] currently outputs HTML files, man pages, and LaTex documents. In a similar vein to the CLI interface,
36
-
we will try to ensure that the three tools described above will not be broken by any changes to the
37
-
outputs. That is, they will succeed and produce ‘correct’ documentation. Although, we don’t make any
38
guarantees about the internal structure of the output documents; e.g., the exact nesting of
39
tags or sequence of LaTex commands may not be preserved. We will attempt to ensure that the HTML anchors are preserved, implying that the filenames will also be preserved.
40
···
45
46
{2 Intermediate Files}
47
48
-
The intermediate files that [odoc] produces ([.odoc] and [.odocl]) should be considered to be internal only
49
and tied to the specific version of [odoc].
···
1
+
{0 [odoc] Interface Guarantees}
2
3
[odoc] has several 'public facing' parts with varying levels of support guarantees.
4
This document describes what those interfaces are, what the support levels are
···
6
7
{2 Documentation Comments}
8
9
+
The first and most important is the syntax of the documentation comments present in the source code.
10
This is relevant to everyone who is writing code that’s intended to be documented by [odoc], so it applies to the widest set of people.
11
We have a separate page describing the {{!page-ocamldoc_differences}markup differences from OCamldoc}.
12
13
{2 CLI Interface}
14
15
+
The way in which we invoke the [odoc] CLI is not trivial, and it requires careful
16
+
ordering and accurate arguments to produce correctly linked documentation. It’s not expected that
17
+
end users will invoke [odoc] by hand, but rather it will be driven by separate tools. As a consequence, it’s important to preserve the tools’ ability to create good documentation with
18
+
each [odoc] release, so we’ll ensure CLI backward compatibility as much as possible.
19
There are currently three ‘first class’ tools that 'drive' [odoc]. We will not make
20
releases of [odoc] whilst knowingly breaking these tools. These are:
21
···
23
- Dune
24
- OCaml
25
26
+
Here, OCaml refers to the newly-merged configure option (from 4.12.0) that builds the standard library documentation with
27
+
[odoc]. If the recommended way of invoking [odoc] changes, we will work with these projects' maintainers
28
+
to ensure they are updated accordingly.
29
30
Additionally, there will be a reference implementation of a tool to build [odoc]'s documentation, which should
31
serve as a guide for anyone building other 'drivers' of [odoc].
···
33
{2 Output Formats}
34
35
[odoc] currently outputs HTML files, man pages, and LaTex documents. In a similar vein to the CLI interface,
36
+
we will try to ensure that any changes to the outputs will not break the three tools described above.
37
+
That is, they will succeed and produce ‘correct’ documentation. However, we don’t make any
38
guarantees about the internal structure of the output documents; e.g., the exact nesting of
39
tags or sequence of LaTex commands may not be preserved. We will attempt to ensure that the HTML anchors are preserved, implying that the filenames will also be preserved.
40
···
45
46
{2 Intermediate Files}
47
48
+
The intermediate files that [odoc] produces ([.odoc] and [.odocl]) should be considered internal only
49
and tied to the specific version of [odoc].