-
Notifications
You must be signed in to change notification settings - Fork 1.1k
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
documentation: centralized and parallel builds #9996
Conversation
The idea sounds fine but I don't like
I would propose either |
The generated documentation also covers part of the compiler library. I think |
356e6ce
to
aa52209
Compare
We discussed this Very Important Naming Question and agreed on |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks generally good except for a few questions left. I am "approving" in advance of @Octachron handling them in a best-effort way.
doc/Makefile.docfiles
Outdated
#************************************************************************** | ||
|
||
define capitalize | ||
$(shell echo $(1) | sed "s/\<./\U&/g") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this magic sed stuff sed "s/\<./\U&/g"
work on exotic systems with old Sed versions? (@Octachron and myself wondered if we should use a small OCaml script instead, but properly dealing with spaces-in-directories might be trickier.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this magic sed stuff
sed "s/\<./\U&/g"
work on exotic systems with old Sed versions?
The \U
replacement (meaning "convert to uppercase", I guess) is no documented in POSIX sed, so the answer is no, it's not going to work everywhere. And it's the first time I see this replacement!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here is a classic sed implementation that I've been using since the 90's:
sed -e 'h
s/\(.\).*/\1/
y/abcdefghijklmnopqrstuvwxyz/ABCDEFGHIJKLMNOPQRSTUVWXYZ/
G
s/\n.//'
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, the good sed scripts are from the 90s :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here is a sed-free solution. Recommended!
define capitalize
$(shell echo $(1) | cut -c1 | tr '[:lower:]' '[:upper:]')$(shell echo $(1) | cut -c2-)
endef
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Then let's go for the recommended solution and a bit of glue rather than a GNUism.
There seems to be a relevant failure that the
|
Indeed, I forgot to update the patch to the CI after @dra27 changes. |
41d945b
to
ca621ba
Compare
This PR proposes to centralize the generation of the documentation for the standard library and the compiler library in one place.
Currently, this build process is scattered between
ocamldoc/
andmanual/
, with slight differences between the two.This PR moves all the documentation generation logic to a new
doc/
directory with the aim to make it easier to tweak the documentation build process (see the next PR).The new Makefile also handles parallel build for the manpages, accelerating the build process, and making it somewhat incremental.