make --scheme file default?

[dsheets]

trafficstars

On 02/06/2015 02:45 PM, Daniel Bünzli wrote:

Le vendredi, 6 février 2015 à 15:34, David Sheets a écrit :

There is the --scheme file option to generate all URLs with /index.html or similar on the end which makes the docs browsable directly from the disk.

You should rather always make the links relative and add the .html (like ocamldoc does) this leaves the problem out, makes the tool simpler to use, and allows too move around/consult the docs without having to bother too much on how they might have been generated in the first place.

The links are already relative. I might change the default but I don't think that the current default mode should disappear. It's not very nice to put '.html' or 'index.html' in your links when they are ultimately meant to be browsed on the web. There are already 3 different representations of the same resource and there will likely be more. We need to help people to talk about the resource rather than a concrete representation.

One benefit of using a local server to browse documentation is that that server can ensure what you are browsing it up-to-date. The documentation files all contain enough information to trace back to the cmti and source code so such a piece of software could achieve "refresh to regenerate" functionality.

I've open

Best,

Daniel

[dbuenzli]

One benefit of using a local server to browse documentation is that that server can ensure what you are browsing it up-to-date. The documentation files all contain enough information to trace back to the cmti and source code so such a piece of software could achieve "refresh to regenerate" functionality.

It's annoying to have to opam doc —serve each time you start a new session. It's annoying to have to go to your terminal to type that command when a bookmark will fail because you forgot to issue the command. Besides think that there will be other, file-based, means to access that documentation (e.g. quick access based on module names through the full-search functionnality of your os/quicksilver/gnome do) and this means these accesses won't open the file through the webserver, resulting in two headed access.

Also think how often your use case is actually going to happen; and when it happens, be really annoying, i.e. made you really loose your time, my bet is not very often, especially if people embed precise information version the generated doc. Finally there are other means to perform what you'd like (e.g. you could ask you preferred browser to refresh the tabs with a given prefix URI after an opam redoc, e.g. by modifying this script).

[dsheets]

It's annoying to have to go to your terminal to type that command when a bookmark will fail because you forgot to issue the command. Besides think that there will be other, file-based, means to access that documentation (e.g. quick access based on module names through the full-search functionnality of your os/quicksilver/gnome do) and this means these accesses won't open the file through the webserver, resulting in two headed access.

I'm not sure what this means. I think this is the best argument for making --scheme file the local default and using --scheme http for publishing.

Also think how often your use case is actually going to happen; and when it happens, be really annoying, i.e. made you really loose your time, my bet is not very often, especially if people embed precise information version the generated doc. Finally there are other means to perform what you'd like (e.g. you could ask you preferred browser to refresh the tabs with a given prefix URI after an opam redoc, e.g. by modifying this script [1]).

This is why there are many interfaces to the tool and libraries. That functionality might be nice. Functionality that uses a local server might be nice, too. I see no issue with supporting multiple URI modes but perhaps the default should be flipped.

[dbuenzli]

Le vendredi, 6 février 2015 à 16:40, David Sheets a écrit :

I'm not sure what this means.

ocamldoc used to generate file with the module name embedded which made it quick to get to a module documentation using os app/file launchers.

I think this is the best argument for making --scheme file the local default and using --scheme http for publishing.

Yes I think file should be the default.

Daniel