Improvements to the manpage #903
Conversation
src/odoc/bin/main.ml
Outdated
| @@ -748,7 +778,8 @@ module Targets = struct | |||
|
|
|||
| let cmd = Term.(const list_targets $ Compile.dst $ Compile.input) | |||
|
|
|||
| let info = Term.info "compile-targets" ~doc:"TODO: Fill in." | |||
| let info = | |||
There was a problem hiding this comment.
This one is a little less obvious - it's quite possible odig is using this. I don't think the reference driver uses it, nor does/will dune, as dune's not really built for dynamic targets.
There was a problem hiding this comment.
Yes it does.
Not sure what's the dune comment is about, but in general it's good for build systems if they can ask the tools which paths they are going to read and write, rather than have build tools guess, discover or hardcode the file systems effects.
(A good example of this is support-files-targets, if all goes well odig will have nothing to do to support the new math support)
There was a problem hiding this comment.
I don't see the point of this command as there's no reason for the compile command to output several files. Especially that it takes a -o.
There was a problem hiding this comment.
Because there's value in operational genericity. If all tools worked that way for all their steps, build incrementalization logics would be fully generic.
This benefits both build system (no tool specific logic) and the tools themselves (they can change the way they want to store intermediate results on the file system without having to bother about existing build logics).
There was a problem hiding this comment.
The output of compile must be given to link and the build system has to know that. I think this adds untested code paths and complexity rather than generality.
The build system must be changed every time Odoc changes so it has to stay simple to be able to adapt fast. Jon mentions Dune because it is built in a way that dynamic targets are hard to represent (a command that outputs an unknown number of files). It's trivial however to have a staticly known list of inputs and outputs.
There was a problem hiding this comment.
We're talking about compile-targets here, not html-targets.
The discussion is running in circle. Goto.
There was a problem hiding this comment.
Your comment doesn't explain why it's such a hassle to express that odoc compile -o foo will write foo but it's convenient to express that it will output the result of odoc compile-targets -o foo.
You have to describe somewhere that odoc compile-targets exists. Please implement it like that in your own DSL:
let compile_targets output = [ output ]
The discussion is running in circle because you refuse to answer my point. We are both talking in the void, it's your fault.
There was a problem hiding this comment.
We are both talking in the void, it's your fault.
Coming from you I will happily take all the blame.
There was a problem hiding this comment.
Please keep the discussion on the code not the people. We're not planning on removing the subcommand, so the discussion is purely about whether we document it in the legacy section or the support section. Since we have at least one user -- odig -- and there is no alternative other than assuming odoc's behaviour, let's put it in the support section.
There was a problem hiding this comment.
You are right, I moved the command to the support section.
|
I've changed the manpage generator tool to parse |
|
Something is going wrong on macOS - CI is failing and I've seen a similar thing locally too. |
|
I've removed the manpage parsing from the |
|
I'd really really prefer not to be parsing the man output. I'd far rather work with the Cmdliner types and generate the |
No. I'm a bit dubious about the usefulness of all this. Man pages are a terrible documentation medium. Keep them at the minimum as the reference for the cli interface and have good high-level docs. I doubt there's much value in having them alongside the If you really have to then |
The sections allow to quickly find the important commands. The "Legacy pipeline" section give less importances to the no longer recommended commands.
Document the dependencies in the compile and link steps. Fill the missing documentation. Improve consistency and formatting.
Sections are assigned while defining the list to make sure they are still in sync.
The output of every 'odoc cmd --help' is wrapped into code blocks and concatenated into a page in the documentation.
Allows to build the documentation on <4.10, as the generating program can't run on these versions. Useful feedback when modifying the CLI. Reduce the complexity of the Dune rules for building the doc. Might allow the reference driver to build it, for example.
Parse the output of 'odoc --help' in a quick and dirty way. It's also possible to parse the name of the section, which is not used yet. 'Unix.open_process_args_in' only works in the intended way on >=4.12. Instead use 'Filename.quote_command', which requires 4.10.
Sections are used to group commands by generating doc sections. The TOC looks more readable. The first section is also nicer with some separations between the list items.
It randomly break on different targets. It should be replaced by something that do not depend on parsing textual output before it can be enabled again by default.
I updated the documentation for some commands and added consistency. Sub commands are grouped and sorted in sections, to show the useful commands first. I also updated some doc strings.
I added some documentation about dependency between compile and link phases.
The last commit concatenate the output of all
--helpinto one page in the documentation. It's not easy to navigate because it's big and the TOC is not very readable. I'm considering generating a different page for each subcommand, what do you think?