Comments (17)
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.
from manual-ocamlbuild.
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?
from manual-ocamlbuild.
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.
from manual-ocamlbuild.
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.
from manual-ocamlbuild.
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!
from manual-ocamlbuild.
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.
from manual-ocamlbuild.
For qtest's readme, I had something like this:
:toc: macro
:toclevels: 4
to make the toc work properly.
from manual-ocamlbuild.
@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?
from manual-ocamlbuild.
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!
from manual-ocamlbuild.
See PR #34.
from manual-ocamlbuild.
I sent a PR to integrate this manual in the ocamlbuild repository: ocaml/ocamlbuild#78
from manual-ocamlbuild.
What's the stable URL I should link to then ?
from manual-ocamlbuild.
@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.
from manual-ocamlbuild.
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.
from manual-ocamlbuild.
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?
from manual-ocamlbuild.
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
from manual-ocamlbuild.
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.
from manual-ocamlbuild.
Related Issues (19)
- Is it possible to control where ocamlbuild outputs the binary symlink? HOT 2
- Restrict to packed usage. HOT 2
- Examples we should have in the documentation HOT 10
- Syntax for union patterns: {..} or \{..\}? HOT 1
- Provide a Unix manual page HOT 3
- Document invocation, options, and target arguments
- how to mimic _tags file within myocamlbuild.ml HOT 10
- how to create files outside of _build HOT 7
- how to use package during plugin compilation HOT 2
- how to split plugin into multiple files
- explain .itarget/.otarget more HOT 4
- Merging the new manual with the new ocamlbuild repo HOT 4
- Outline
- Example of custom utop build
- new optimization tags for flambda HOT 1
- -cflags, -lflags HOT 2
- `-plugin-tag` not available on my ocamlbuild HOT 2
- list of available tags HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from manual-ocamlbuild.