-
Notifications
You must be signed in to change notification settings - Fork 15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
overhaul documentation completely #34
Conversation
* Replace Markdown with Asciidoctor markup. * Make a distinct CONTRIBUTING.adoc document, following GitHub conventions. * Add produced HTML and PDF versions of the manual. * Use a tabular presentation in manual where more appropriate than past presentation. * Add a directory for incomplete code samples, samples/. * First work towards sourcing incomplete code samples instead of including them verbatim in the manual text. * Be more consistent in use of `ocamlbuild` vs. OCamlbuild. For any tool now, `tool` is used when the CLI utility is meant vs. Tool when software product as a whole is meant. * Add TODO comments in manual for existing parts that need expert attention.
The sample include syntax, used at the very end of the manual, does not work on GitHub yet it does in the rendered documents pushed to the repo. Allegedly there is a workaround, but I haven't managed to get that working quickly. |
This is very nice work, thanks! I have a few minor comments on the current PR state:
On the rendering side, note that @linding has been independently working on a nice stylesheet for the markdown rendering, see his repository and the rendered document. I'm afraid most of that work would have to be redone after the AsciiDoc switch, but hopefully you can join forces to get a html rendering that you both like. |
Add text besides glyphs. Replace skull-and-bones glyph with caution sign glyph.
The link you gave to @lindig's styled document actually does not show more styling at all compared to the GitHub-rendered Markdown document, and certainly less than the Asciidoctor document rendered to HTML and PDF. Are you sure this was the work he intended you to reference? @lindig: It would be great if we can keep up the good work together! In fairness, there is also another PR #30 that you did not yet address @gasche. Do you wish to merge the PR? We can address remaining issues later, agree? |
Thanks for the careful response. I squashed all the commits into one, and merged the result. Thanks a lot again for your work. The TODOs that you have added in the text are also very helpful, I will try to correct them over time. Thanks for the pointer to #30; I did, of course, forget about it. That means that now I have to port it to the new syntax. |
P.S.: when doing the merge into the ocamlbuild repository, I intend to keep the commit history. If only, that's more respectful to the contributors whose work is visible through the history. |
@sanmai-NL , could you give some advice on the preferred way to reference sections? It seems that AsciiDoctor generates a default anchor name by mangling the title name, which is good. But if I want to explicitly reference a section, I add a This has unfortunate consequences in terms of upward-compatibility of links: if users today refer to a specific section with an auto-generated anchor, and I later decide to point to this section from another part of the document, the auto-generated will become invalid in future versions of the document. I would suggest to always explicitly give an anchor at each section level (for example reusing the naming scheme I used in the markdown version); this also has the advantage that the anchor is robust to minor changes in the title. Is this standard practice, or is there a better way? |
The point of rendering of manual.md into a self-contontained single manual.html file was to be independent of the rendering GitHub provides server side. However, the style file indeed mimics the GitHub style.
— Christian |
@gasche: |
Thanks for the information. (Note that it shouldn't be to hard to generate dummy |
Are you sure about this? I have serious doubts. Perhaps the real issue is that we still should identify the version of the manual (in a simple form, equal to the version of About the ID naming scheme, please do mind that the namespace of any ID you assign is clear. If I recall correctly, your previous naming scheme did not distinguish e.g. tables from sections. |
Adding a label to each object is not an issue, as object declaration already take linear space, so the amortized complexity cost of labels is nil. We have two choices in how we release rendered versions of the document. We can have the version in the URL, but then (because URLs should be persistent) that means that the storage space grows linearly over time. We can have a single available "last version", and then we need to try to have labels as future-compatible as possible (within the limits of what is reasonable). Also this has the advantage that references self-improve (if I link to a section today, but you read it tomorrow, you'll benefit from fixes/clarifications made in the meantime). |
I think that for the online version this is the simplest and most reasonable thing to do. While annoying I think it is ok for #id's to sometime fail (though that should be minimized), you can often retrieve what you want by considering the context in which the URI was published. What is more annoying is when the URI itself changes. |
@gasche: I shall point out again, that the idea that one can safely and durably link to any section of an evolving document can turn out to be quite misguided. I do see the value of having a URL that points to current version of the manual. But that is simply a matter of configuring a web server, or making a symlink, etc. I'm just contributing to this project here, I am not aware of any plans on your side about self-hosting OCamlbuild materials. |
This PR addresses textual as well as technical issues. A summary of the changes is given in the commit message.
The main change is a documentation markup language translation from GitHub Flavored Markdown to Asciidoctor. In my opinion, my translation has delivered promising results. Since the Asciidoctor markup has turned out very powerful, readable and concise, this work/experience could be re-used for future documentation work on other OCaml-related projects, such as the OCaml distribution itself. Some slight issues in which peculiarities of OCaml vs. Asciidoctor syntax have conflicted have been reported upstream.