'make docs' target: Why are these files not installed?

[jkeenan]

[Moving discussion of this issue from TT #1922, comment 7]

When you configure with a --prefix directory, then build and proceed to install documentation ...

perl Configure.pl --prefix=/path/to/parrot
make
make install-doc

... you will get documentation installed under

/path/to/parrot/share/doc/

So far so good.

If you then call make docs, you generate documentation for about 14 files. But this documentation is placed under your build directory, not under your install directory:

./docs/doc-prep
./docs/ops/bit.pod
./docs/ops/cmp.pod
./docs/ops/core.pod
./docs/ops/experimental.pod
./docs/ops/io.pod
./docs/ops/math.pod
./docs/ops/object.pod
./docs/ops/pmc.pod
./docs/ops/set.pod
./docs/ops/string.pod
./docs/ops/sys.pod
./docs/ops/var.pod
./docs/packfile-c.pod

Is this what we expect? Is anyone familiar with the history of make docs enough to venture an opinion?

Thank you very much.

kid51

[jkeenan]

Further investigation shows that POD for the ops listed in the make docs part of the Description is indeed installed along with all other POD:

ls -lS /tmp/pseudoinstall/share/doc/parrot/2.11.0-devel/pod/ops/
total 68
-rw-r--r-- 1 jimk jimk 13516 Jan  8 19:27 core.pod
-rw-r--r-- 1 jimk jimk  8263 Jan  8 19:27 string.pod
-rw-r--r-- 1 jimk jimk  7886 Jan  8 19:27 cmp.pod
-rw-r--r-- 1 jimk jimk  6040 Jan  8 19:27 pmc.pod
-rw-r--r-- 1 jimk jimk  5511 Jan  8 19:27 math.pod
-rw-r--r-- 1 jimk jimk  5389 Jan  8 19:27 var.pod
-rw-r--r-- 1 jimk jimk  4615 Jan  8 19:27 object.pod
-rw-r--r-- 1 jimk jimk  3678 Jan  8 19:27 set.pod
-rw-r--r-- 1 jimk jimk  2064 Jan  8 19:27 experimental.pod
-rw-r--r-- 1 jimk jimk  1780 Jan  8 19:27 bit.pod
-rw-r--r-- 1 jimk jimk  1754 Jan  8 19:27 sys.pod
-rw-r--r-- 1 jimk jimk  1046 Jan  8 19:27 io.pod

versus

$ ls -lS docs/ops/
total 68
-rw-r--r-- 1 jimk jimk 13516 Jan 11 21:56 core.pod
-rw-r--r-- 1 jimk jimk  8263 Jan 11 21:56 string.pod
-rw-r--r-- 1 jimk jimk  7886 Jan 11 21:56 cmp.pod
-rw-r--r-- 1 jimk jimk  6040 Jan 11 21:56 pmc.pod
-rw-r--r-- 1 jimk jimk  5511 Jan 11 21:56 math.pod
-rw-r--r-- 1 jimk jimk  5389 Jan 11 21:56 var.pod
-rw-r--r-- 1 jimk jimk  4615 Jan 11 21:56 object.pod
-rw-r--r-- 1 jimk jimk  3678 Jan 11 21:56 set.pod
-rw-r--r-- 1 jimk jimk  2064 Jan 11 21:56 experimental.pod
-rw-r--r-- 1 jimk jimk  1780 Jan 11 21:56 bit.pod
-rw-r--r-- 1 jimk jimk  1754 Jan 11 21:56 sys.pod
-rw-r--r-- 1 jimk jimk  1046 Jan 11 21:56 io.pod

So my guess is that make docs is a vestige of some early, vintage-2003 documentation schema. That suggests that the all part of the docs Makefile -- generated from config/gen/makefiles/docs.in and earlier still from config/auto/perldoc.pm is entirely superfluous.

Does that analysis seem correct?

kid51

[jkeenan]

whiteknight indicated on IRC that he probably took this ticket by accident. I'm taking it back (not that I know what to do for it yet :-) ).

kid51

[jkeenan]

Unless someone advises otherwise, after 3.0 I will work to eliminate this target. There's no point in installing a very small subset of our POD in directories under the build dir when we're also installing them in a reasonable location underneath the install dir.

We would then be free to re-define make docs in a more useful way. Any suggestions?

Thank you very much.

kid51

[jkeenan]

Have begun work on elimination of make docs in the tt1954_eliminate_make_docs branch. Still open to feedback on this.

kid51

[jkeenan]

first attempt at removing 'make docs'

[jkeenan]

The patch I just attached documents the difference between the current state of the tt1954_eliminate_make_docs branch and the point where it was forked from master.

Please review. mikehh: I'd be particularly interested in your comments; I want to make sure I didn't damage make html.

kid51

[jkeenan]

Would anyone else like to comment on this patch eliminating make docs?

Thank you very much.

kid51

[coke]

It looks like your patch isn't just removing 'make docs', but redoing how "make html" is done. Is that intended?

[mikehh]

had problems with the branch see  http://nopaste.snit.ch/29545

[jkeenan]

Replying to mikehh:

had problems with the branch see  http://nopaste.snit.ch/29545

I looked at that paste. My hunch is that in the directory tree where you were working, you had previously called perl Configure.pl --configure_trace. You then checked out the new branch and called that again without an intervening make realclean. That meant that the Storable file holding the trace data was appended to, rather than being regenerated from scratch.

This is a mistake I've made, and it always becomes manifest as a failure in the postconfiguration test where you had an error. A make realclean solves it.

Mike, as the author of Parrot::Configure::Trace, I'm glad to see that there is at least one other person in the world who uses it :-) . But since it's intended to be a diagnostic for what, these days, are relatively infrequent problems in the configuration process, and since its own code is quite stable, you don't really need to run --configure_trace on every test run.

The more important question: Is coke correct is saying that this branch screws up make html?

Thank you very much.

kid51

[coke]

>  The more important question:  Is coke correct is saying that this branch
>  screws up `make html`?

I'm just noting that you're changing it, not that you're breaking it.

-- 
Will "Coke" Coleda

[mikehh]

I am still getting a configuration failure on the branch. [from a new clone]

$ git checkout tt1954_eliminate_make_docs
Switched to branch 'tt1954_eliminate_make_docs'
$ perl Configure.pl
Parrot Version 3.0.0 Configure 2.0
Copyright (C) 2001-2011, Parrot Foundation.
...
...
gen::makefiles -      Generate makefiles and other build files...
step gen::makefiles died during execution: Can't open html/Makefile.tmp: No such file or directory at lib/Parrot/Configure/Compiler.pm line 388.

 at Configure.pl line 77

gen::config_pm -      Record configuration data for later retrieval......done.
During configuration the following steps failed:
    62:  gen::makefiles
You should diagnose and fix these errors before calling 'make'

[jkeenan]

Replying to mikehh:

I am still getting a configuration failure on the branch. [from a new clone]

Thanks. Will investigate. Fortunately this is a minor priority task.

kid51

[jkeenan]

Replying to mikehh:

I am still getting a configuration failure on the branch. [from a new clone] {{{ $ git checkout tt1954_eliminate_make_docs

I wonder: Shouldn't that have been:

git checkout -b tt1954_eliminate_make_docs

... on a sufficiently modern version of git?

On my older version of git, I did this:

$> git clone git@github.com:parrot/parrot.git
$> cd parrot
$> git checkout --track -b tt1954_eliminate_make_docs
$> perl Configure.pl && make && make html

resulting in:

make[1]: Entering directory `/home/jimk/tmp/parrot/docs'
/usr/local/bin/perl -I../lib ../tools/docs/make_html_docs.pl 
   --version=3.0.0-devel
make[1]: Leaving directory `/home/jimk/tmp/parrot/docs'

$> find docs/html -type f -name '*.html' | wc -l
234

So I can't reproduce your failure.

kid51

[jkeenan]

Replying to mikehh:

I am still getting a configuration failure on the branch. [from a new clone]

On a further attempt, I got the same failure you reported. As a workaround, I have guaranteed the existence of an html directory by planting a little README file therein and adding that to git. See commit 81165eb.

Are there more elegant ways of doing this? Undoubtedly, but here I've reached the limits of my understanding of Makefiles. However, the point of this ticket was to eliminate the currently superfluous make docs target, which was creating duplicates of certain .pod files, while not damaging make html. I believe I am accomplishing that.

Comments?

Thank you very much.

kid51

[coke]

Attached a patch against master that removes top level make docs target, changes cd docs && make all to just show the help, and removes the tasks the old "all" target did.

I think this covers the original request of the ticket, which I took to be "don't bother creating these local .pod files that don't get installed.)

Regards.

[coke]

On Fri, Feb 18, 2011 at 9:55 PM, Parrot <parrot-tickets@lists.parrot.org> wrote:
> #1954: 'make docs' target:  Why are these files not installed?
> ---------------------+------------------------------------------------------
>  Reporter:  jkeenan  |       Owner:  jkeenan
>     Type:  bug      |      Status:  assigned
>  Priority:  minor    |   Milestone:
> Component:  docs     |     Version:  2.11.0
>  Severity:  low      |    Keywords:
>     Lang:           |       Patch:  new
>  Platform:           |
> ---------------------+------------------------------------------------------
>
> Comment(by jkeenan):
>
>  Replying to [comment:11 mikehh]:
>  > I am still getting a configuration failure on the branch.
>  > [from a new clone]
>  >
>
>  On a further attempt, I got the same failure you reported.  As a
>  workaround, I have guaranteed the existence of an ''html'' directory by
>  planting a little ''README'' file therein and adding that to git.  See
>  commit 81165eb.
>
>  Are there more elegant ways of doing this?  Undoubtedly, but here I've
>  reached the limits of my understanding of Makefiles.  However, the point
>  of this ticket was to eliminate the currently superfluous `make docs`
>  target, which was creating duplicates of certain ''.pod'' files, while not
>  damaging `make html`.  I believe I am accomplishing that.
>
>  Comments?
>
>  Thank you very much.
>
>  kid51
>

I'm very confused as to why we now have  a top level html/ directory
when we didn't have that before, even after "make html".

Is the goal of this ticket just to not generate the local .pod files
(mostly under docs/ops)? I'm sure we can remove those more surgically.



-- 
Will "Coke" Coleda

[jkeenan]

Replying to coke:

I think this covers the original request of the ticket, which I took to be "don't bother creating these local .pod files that don't get installed.)

Yes. I had to remove the docs-clean from the clean target to get make clean and make realclean to work properly. Applied via 6ac86c9 3c8fed0 and c743d11.

Closing ticket and removing original tt1954_eliminate_make_docs branch from github.

Thank you very much.

kid51