Skip to content
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

Closed
vicuna opened this issue Jun 6, 2015 · 11 comments
Closed

Allow OCaml manual to be built independently #6895

vicuna opened this issue Jun 6, 2015 · 11 comments

Comments

@vicuna
Copy link

vicuna commented Jun 6, 2015

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

@vicuna
Copy link
Author

vicuna commented Jun 7, 2015

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.

@vicuna
Copy link
Author

vicuna commented Jun 7, 2015

Comment author: @Octachron

I spent some time to build the manual recently. I followed these steps:

  • clone the repository
  • build the tools in ocaml-manual repository with "make tools"
  • from the parent directory, create a symlink "release" to ocaml source repository
  • build a working compiler in the source repository
  • update LD_LIBRARY_PATH to have dllunix.so and dllcamlstr.so in path
    (they are originally in ocaml/otherlibs/{unix,str} )
  • building the manual should work from there except for external dependencies:
    in particular hevea and ed are dependencies.

I am sure there is a better way to build the manual, but at least it worked for me.

@vicuna
Copy link
Author

vicuna commented Jun 8, 2015

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.

@vicuna
Copy link
Author

vicuna commented Jun 10, 2015

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...

@vicuna
Copy link
Author

vicuna commented Jun 11, 2015

Comment author: @damiendoligez

What is the license for this part of the repository? It seems to be missing a LICENSE file...

One more thing for the developers' to-do list: choose a CC license for the manual.

@vicuna
Copy link
Author

vicuna commented Jun 19, 2015

Comment author: @johnwhitington

README.txt attached, tested on Linux and OS X.

@vicuna
Copy link
Author

vicuna commented Jun 19, 2015

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 make-tools in trunk (manual)"), and "(compiler)" for the compiler-related places.

(The confusion is of course not John's fault, and we should think of renaming the SVN directory into "ocaml-manual" rather than "ocamldoc".)

@vicuna
Copy link
Author

vicuna commented Jun 22, 2015

Comment author: @johnwhitington

README-improved.txt contains changes as requested.

@vicuna
Copy link
Author

vicuna commented Jun 23, 2015

Comment author: @gasche

Thanks, the new version is very good.

@vicuna
Copy link
Author

vicuna commented Jun 30, 2015

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/),)
SRC = ../../release
else
SRC = ../release
endif

(I had to change some other part of the Makefile as this directory is again hardcoded as CSLDIR in manual/library/Makefile.)

@vicuna
Copy link
Author

vicuna commented Jun 30, 2015

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants