On Feb 22, 2006, at 9:38 AM, Will Coleda wrote:
On Feb 22, 2006, at 6:03 AM, Karl Forner wrote:
Hello,
I've played a little with 'make html', and the docs produced seem
to me much
more useful than the docs available on the parrotcode.org website.
What I particularly appreciate is the hyperlinks to other pod
documents and
the ability to browse the source code, the examples, the tests and
so on.
Concerning the hyperlinks, I noticed that for now, in order for
the links F<
foo.pod> to work, I had to give the relative path from the root of
the
parrot checkout, even if the file referencing the other is in the
same
directory.
Let me clarify a bit:
in docs/parrot.pod, using "make html", the link produced by
"F<intro.pod>"
does not work while
"F<docs/intro.pod>" does work.
So at last my questions are:
- is this the canonical/correct way of referencing files ? In that
case
should I correct all pod files ?
Canonical or not, "working" wins at the moment, I'd wager.
- Is it planned that the html documentation produced by "make
html" will
replace the current website documentation ?
Well, everything in the docs dir on the website *is* the
documentation from the repository. There's a separate svn
repository which points at the various documentation from the
parrot repo - having something that requires little care and
feeding aside from parrot repo itself is the most desirable. As it
is, we have to tweak the website repo when documentation is added
or modified.
Er, whenever *files* are added or *renamed*. Minor changes to the
documentation in an existing file requires no changes to the website,
they are automatically propagated after the cache expires.
Other than that, we don't have to touch it. If you know of files
that are missing, make a list, I can patch this up.
As for being able to browse the source - there's a link to browse
the svn repo on the website - I don't think we need a *strict* one
to one correspondence between the website and make html.
- Are there some documentation that I missed about how to write
parrot
documentation (POD syntax, guidelines etc...) ?
Dunno. If you can't find it, it's clearly not in the right spot,
anyway. =-)
Thanks
Karl
