Is there any reason to no integrate this in the ocamlbuild project ?

[gasche]

Is there any reason to no integrate this in the ocamlbuild project ?

[william3]

To comment on the initial question, I think this manual is already very nice, and should improve with time, so I would not consider it as a draft.

[gasche]

The bad reason is that it feels a bit too drafty right now to go in the "official" documentation. The good reason is that I did not take the time to do it yet.

I would like to take the opportunity to turn it into an AsciiDoc document, to get the nice table-of-contents generation and generally better features (and worse syntax), but if someone beats me to it and just submits a simple pull-request for inclusion in the right place I won't complain.

What would a good stable URL be for this? A github.io page in the ocamlbuild project? Would we have to write a Makefile to do the actual rendering, then, or does Github support rendering on their side for those pages as well?

[dbuenzli]

The bad reason is that it feels a bit too drafty right now to go in the "official" documentation. The good reason is that I did not take the time to do it yet.

Ok. But it describes a few things, e.g. ocamlfind packages that are not described in the official docs.

What would a good stable URL be for this? A github.io page in the ocamlbuild project?

Sounds reasonable.

Would we have to write a Makefile to do the actual rendering, then, or does Github support rendering on their side for those pages as well?

No idea. But I'd suggest to do the rendering yourself, here's a script that automates the publication of a bunch of files on github pages which shouldn't be too hard to adapt.

[sanmai-NL]

My two cents before you commence rewriting the documentation in another markup format. What about Pandoc Markdown vs. AsciiDoc(tor)? The latter does not support e.g. citations, as far as I know. The former is better supported by the well-maintained and feature-complete Pandoc tooling. AsciiDoc(tor) has a more natural and elegant syntax than Markdown, IMO. Also, AsciiDoctor has very good macro-like features, e.g. file snippet inclusion.

[gasche]

During the writing of this manual I saw value in the fact that it was rendered directly on its github page. Once it is released, it may have a rendered static version, which makes the issue less important, but the reason I considered AsciiDoc above is that github renders it (this idea was given to me by @c-cube which did a similar transformation on the compiler's INSTALL and README files).

I'm a pandoc fan (I like using good tools written in good languages) and use it for my personal documents, but I feel that a well-documented and standardized format would be the better choice here. (I'm not fond of the AsciiDoc syntax which felt sensibly heavier than Markdown's to me, but I'm fine with using it still).

@sanmai-NL, if you were interested in contributing the translation to the AsciiDoc format (which you seem more familiar with), that could be very nice!

[sanmai-NL]

Rendering the ToC from an AsciiDoctor document on directly on GitHub did not work for me in this document (also a helpful example of how to use the various AsciiDoctor features). As a workaround I rendered the document to HTML and put that in the repo alongside the AsciiDoc source, and then linked to it from a GitHub CDN. See https://github.com/clarin-eric/SPF-tutorial/blob/master/README.adoc. But I strongly favor Daniel Bünzli's GitHub pages solution instead.

I'd enjoy helping out, but I do not have much time either. If the documentation work is clearly specified and broken down, I can take up one such ticket.

[c-cube]

For qtest's readme, I had something like this:

:toc: macro
:toclevels: 4

to make the toc work properly.

[sanmai-NL]

@gasche: Good news, I've completely rewritten the manual in Asciidoctor. The results are very good, the document has become far easier to maintain and read. Could you quickly make an Asciidoctor branch on this repo that I can push to, in one big commit? Or perhaps one in the ocamlbuild repo itself?

[gasche]

You could send a PR here to completely replace the markdown version of the manual (in master). The short-term plan is indeed to put the manual in ocamlbuild, but we can do this in two steps, first convert here and then move to there. Thanks for your help!

[sanmai-NL]

See PR #34.

[gasche]

I sent a PR to integrate this manual in the ocamlbuild repository: ocaml/ocamlbuild#78

[dbuenzli]

What's the stable URL I should link to then ?

[sanmai-NL]

@dbuenzli: Based on what I know, an URL into the relevant GitHub repository (e.g., current revision on master branch). If my new PR #35 is merged, every (ocamlbuild) release on GitHub is to receive an HTML and PDF attachment with the manual, which you could link to as well.

[dbuenzli]

Based on what I know, an URL into the relevant GitHub repository (e.g., current revision on master branch).

That's not what I call a stable URL.

[sanmai-NL]

I see that point, but I do not know about the possibilities outside that. What specific threats to the URL availability and persistence do you have in mind? Could an actively maintained redirect from a stable website such as ocaml.org be a solution?

[dbuenzli]

Le lundi, 2 mai 2016 à 11:08, Sander Maijers a écrit :

I see that point, but I do not know about the possibilities outside that. What specific threats to the URL availability and persistence do you have in mind? Could an actively maintained redirect from a stable website such as ocaml.org (http://ocaml.org) be a solution?

A publication on github.io would be fine. Just an URL that is vaguely user friendly, not tied to the current repository structure and agnostic to the current publication format.

Daniel

[gasche]

So the merge is done in the ocamlbuild repository, see ocamlbuild/manual/manual.adoc. I need to wrap up the present repository by merging or porting remaining PRs, and solving or porting remaining issues.