Manual: unify compilers/toplevel options at source level#491
Manual: unify compilers/toplevel options at source level#491gasche merged 5 commits intoocaml:trunkfrom
Conversation
| \notop{% | ||
| \item["-a"] | ||
| Build a library(\qcma\nat{ and ".a"/".lib"} file\nat{s}) | ||
| with the object files (\qcmo\nat{ and ".o"/".obj" files} files) |
| \nat{For} instance, | ||
| "-ccopt -L"\var{dir} causes the C linker to search for C libraries in | ||
| directory \var{dir}. \comp{(See the "-custom" option.)} | ||
| }%notop |
There was a problem hiding this comment.
I think that readability could be improved here by duplicating the "for instance" sentence instead of trying to share at such a fine granularity.
There was a problem hiding this comment.
I think that duplicating the introductory clause should work fine, but I am probably biased against duplication.
| compiled interface files (".cmi"), compiled object code files | ||
| (\qcmo), \nat{and }libraries (\qcma) | ||
| \comp{, and C libraries specified with "-cclib -lxxx"}.}%notop | ||
| \top{source and compiled files.} |
There was a problem hiding this comment.
Again, readability could be improved by duplicating the first sentence into three complete versions.
There was a problem hiding this comment.
Like before, I will try first to just duplicate the adverbial for clause.
| \notop{% | ||
| \item["-output-obj"] | ||
| Cause the linker to produce a C object file instead of \comp{a bytecode} | ||
| \nat{an} executable file. This is useful to wrap OCaml code as a C library, |
There was a problem hiding this comment.
\comp{a bytecode file}\nat{an executable file}. Having self-contained fragments in the conditionals helps readability.
| Print all external commands before they are executed, | ||
| \nat{in particular invocations of the assembler, C compiler, and linker.} | ||
| \comp{in particular invocations of the C compiler and linker | ||
| in "-custom" mode. Useful to debug C library problems.} |
There was a problem hiding this comment.
Couldn't the last sentence be present in both outputs?
|
(I had not noticed this PR previously, apologies.) I think that it is a good idea, and that the readability cost can be made fairly small (see comments inline; I think we can make the source "read" better by introducing some reduplication where full factoring gives something too fine-grained). I would wait after the release that Damien is currently working on, and then merge it in trunk unless someone objects. |
This commit creates a file unified-options.etex which regroups at source level the description of the compilers and toplevel options. Difference of options between native/bytecode compilers and toplevel are handled via conditional tex macros.
bf54e6d to
101a009
Compare
|
Thanks @gasche for the suggestion. You are right duplicating isolated fragments have improved the readability. I have rebased this PR to integrate your suggestion and new options (except the ones not yet merged in trunk (e.g. ocamlparam option)). I have also added a short description in the manual readme to (potentially) help people find the right file to edit in order to add new options. Another point, sometimes the toplevel referred to the option description in |
|
I see no reason not to merge, so I merged. Thanks for the nice work! |
…ptions Manual: unify compilers/toplevel options at source level
Co-authored-by: mirzababarbaigbukhari <mirzababar@thesmallsquare.com> Co-authored-by: Thibaut Mattio <thibaut.mattio@gmail.com>
This pull request proposes to unify the description of the options of the bytecode compilers,
native compilers and toplevel at the source level.
Currently, these descriptions are kept separated in their respective manual section with a significant overlap between these sections. This duplication increases the risk of desynchronisation between the different options and impedes the propagation of typographic error corrections.
With this PR, all these options section are merged together in
manual\manual\cmds\unified-options.etex. The difference of options between compilers and toplevel are then handled using conditional tex macros. The compilers and toplevel sections then set the right boolean parameters and include theunified-options.etexfile. This means that are the descriptions are still duplicated in the generated manual.I have tried to keep the readability cost of this unification as low as possible, however it is clear that this cost is non-zero.