[erlang-questions] FOP (was: Re: Trace-Driven Development)

[Ulf Wiger]

On 7 Jun 2012, at 10:06, Gustav Simonsson wrote:

> Today the OTP team have dedicated resources for reviewing patches. This means that
> if you write a documentation patch it's almost guaranteed to be included following a review,
> provided it improves the documentation. The time to review a documentation change is also
> typically much shorter compared to reviews of code changes, and can often be done by
> more team members.

As Richard pointed out, the wiki page on submitting patches
could be extended with some helpful tips on how to make
documentation patches.

At the very least, the github wiki should have a link to the OTP 
installation guide,

http://www.erlang.org/doc/installation_guide/INSTALL.html

which among many other things covers what to do when you
run into problems with FOP. For those just wanting to patch
the docs of a single app, it would of course be better to learn
how to avoid FOP entirely, and perhaps even a sneaky way
not to have to build *all* the docs.

Here's a practical result:

Now, the installation manual above says that `make` takes
about 5 minutes on a fast machine. I'm not sure what kind of
machine that is, but as an alternative data point, it takes 
21 minutes on my fairly new MacBook Air with a 1.7 GHz
Core i5, 4GB RAM and an SSD. It saddens me to find out
how 'unfast' it is.

Running `make doc` with fakefop on the same machine
takes 7 minutes.

(I had FOP installed before, but uninstalled it since it 
drove me nuts).

Once all this is done, stepping down into e.g. sasl
and running `make docs` there takes less than a second.

Unfortunately, this is not enough to verify the docs 
entirely, since I don't get the frame layout.

(The wiki says to use `make release_docs`, which
is good advice. The INSTALL guide starts out with
`make doc`, and then enters into a discussion about 
targets, which doesn't necessarily help me understand
which one will make the html docs render right in my 
browser).

However, running `make release_docs` afterwards
(45 secs, since docs are already made), produces the
full HTML docs  under $ERL_TOP/release/doc/index.html

Once at this point, making a change, running 
`make release_docs` at the app level, and refreshing
the web page, is very quick.

BR,
Ulf W


Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com