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
Allow OCaml manual to be built independently #6895
Comments
Comment author: @gasche That's a very good idea. I don't quite remember how I got the manual to build -- I had to tinker a bit, but I only remember creating a symbolic link from somewhere to an OCaml source repository. This should be a low-hanging fruit for an external contribution: if you're reading this, feel free to build the manual, document your steps along the way, and why not try to add a more self-contained Makefile target. |
Comment author: @Octachron I spent some time to build the manual recently. I followed these steps:
I am sure there is a better way to build the manual, but at least it worked for me. |
Comment author: @damiendoligez What we need is a README to explain all the steps of building the docs (and maybe to simplify or automate some of those steps). octachron's post is a pretty good starting point for this README. |
Comment author: @johnwhitington I have managed to build it now, following these instructions, on OS X. I will provide a README file soon, once I've tested on Linux and Windows. What is the license for this part of the repository? It seems to be missing a LICENSE file... Also, I assume this too invasive to fix, but does this directory in the repository have to be called "ocamldoc"? It's very confusing, since the "ocamldoc" tool source is in the "ocaml" directory... |
Comment author: @damiendoligez
One more thing for the developers' to-do list: choose a CC license for the manual. |
Comment author: @johnwhitington README.txt attached, tested on Linux and OS X. |
Comment author: @gasche This is very good, thanks! I would be interested in seeing two improvements to this already-very-nice README.txt. (I may try to make them myself if/when I get time and motivation, but any should feel free to step up and propose an updated file). (1) I think we should also advertise the github projects that can be cloned as alternatives to svn checkout (because more and more people are more familiar with git-centric workflows). Both for git and svn, providing explicit URLs would be helpful. (2) We should make it more explicit in the naming of various things what is about the OCaml compiler sources, on one hand, and what is about the OCaml manual sources, on the other. "trunk" is confusing as it may apply to both, and "ocamldoc" is confusing as it may also refer to a directory in the OCaml distribution. I would suggest to just append "(manual)" for the manual-related places (eg. "in the ocamldoc (manual) repository", or "run (The confusion is of course not John's fault, and we should think of renaming the SVN directory into "ocaml-manual" rather than "ocamldoc".) |
Comment author: @johnwhitington README-improved.txt contains changes as requested. |
Comment author: @gasche Thanks, the new version is very good. |
Comment author: @gasche So I just tested the instructions, and there is a small issue with the placement of the release symbolic link: in the Git mirror, it should be placed in the parent directory of the git repository. (With SVN the natural checkout method has one more directory layer, so it is fine.) Rather than codifying this wart in the README, I decided to change the Makefile to first check whether ../release exists (from the perspective of the "manual" subdirectory), and only if it doesn't look at ../../release. I'm far from a Makefile expert, so please complain if the conditional below looks wrong to you: ifeq ($(wildcard ../release/),) (I had to change some other part of the Makefile as this directory is again hardcoded as CSLDIR in manual/library/Makefile.) |
Comment author: @gasche I merged your file, with some light changes (I pointed out that hevea is available via OPAM, and removed the "you should see this" that is SVN-based and could confuse users of the git mirror; with the relaxed code for finding "release", this should not be too error-inducing). Should we have a Changelog file for the manual proper? We don't for now, so attribution is only tracked in commit messages, which may be a bit light. If external contributors feel that a proper Changelog could be helpful, I can try to create one (for future contributions). |
Original bug ID: 6895
Reporter: @johnwhitington
Assigned to: @gasche
Status: closed (set by @xavierleroy on 2017-02-16T14:16:46Z)
Resolution: fixed
Priority: normal
Severity: minor
Version: 4.02.1
Target version: 4.02.3+dev
Fixed in version: 4.03.0+dev / +beta1
Category: documentation
Tags: junior_job
Related to: #7047
Monitored by: @gasche @dbuenzli
Bug description
I'd like to work on Bug 6676, and do some other work on the documentation. However, it's better to be able to build it locally, rather than presenting patches to the source blind.
As of now, the code in the SVN repository at /ocamldoc/ doesn't seem to build, relying on a number of external files and environment variables which are not present.
Would it be possible to fix this, or if not, to provide instructions on how to do a "dummy" build? I looked at "csl-checklist" and "ocaml-development-process" and couldn't find anything.
Why is the documentation build system not in /ocaml/ anyway? If it could be made to build on any platform, it would be easier to keep is sync? The dependencies would have to be clarified, of course, and building it would be an optional part of building the compiler.
File attachments
The text was updated successfully, but these errors were encountered: