On Mar 9, 2009, at 20:59, [email protected] wrote:
Here's how I see the Guide at this time w.r.t. what kind of person
should read that section:
1. Introduction -- all users
2. Installing MacPorts -- all users
3. Using MacPorts -- all users
4. Portfile Development -- port maintainers
5. Portfile Reference -- port maintainers, except that regular users
might well want to know about the different phases that MacPorts goes
through to install a port; or that ports can have dependencies and
what MacPorts does about that (i.e. it works out and installs the
dependencies first in the correct order); or that ports can have
startupitems and how that works
6. MacPorts Internals
6.1. File Hierarchy -- all users
6.2. Configuration Files -- advanced users
6.3. Port Images -- all users
6.4. APIs and Libs -- developers of GUI clients
6.5. The MacPorts Registry -- base developers
7. MacPorts Project -- all users
8. MacPorts Guide Terms
Glossary -- no users (doesn't actually define any terms)
Yeah I think that pretty much describes the user/information
mapping as it
is. Though it is all subject to change as time goes on, what do
you think
of the overall structure right now? I would be interested to know
your
opinion. As I said before, it could be that the "internals"
section ought
to be in another document. But I'm not sure what it would be. I just
looked at the FreeBSD Porter's Handbook, and it has a "Quick
Porting" and
"Slow Porting" section. That's interesting and doesn't get into
"basic"
and "advanced" categories.
I may have to look at that document. I know virtually nothing about
FreeBSD.
Among the projects I'm involved with in some way, I consider the gold
standard of documentation to be that of Subversion. Take a look just
at the index:
http://svnbook.red-bean.com/en/1.5/index.html
Tons of categories. It begins with book-like stuff like Foreword and
Preface. The Audience section says who the book is written for. How
to Read This Book calls out different types of users and which
sections they should read. It talks about how the book is organized.
It has a section called What is Subversion; I like that section title
very much. It also has a section on Subversion's history. It was
written by a small team of writers who had a cohesive vision for the
book. And it has been printed in hardcopy by O'Reilly; a second print
edition is in the works.
Another project whose documentation I like is Graphviz, in the way it
documents all the options one can use in a graph:
http://graphviz.org/doc/info/attrs.html
It's not a book, just a single long page, but it goes into great
detail about each option, under what circumstances it can be used,
what its default value is, what valid values are, how options relate
to one another, and so forth. We do this to some extent too in the
guide for portfile options but in many cases we don't really explain
things:
* "platforms" says "The platforms on which the port has been tested"
but doesn't say what values are available for this variable (answer:
I'm not sure where the full list is) and what effect setting it has
(answer: none at all; maybe in the future MacPorts will warn if you
try to install the port on a platform it doesn't indicate
compatibility with).
* For "homepage" it says "Port application's homepage" but doesn't
say what effect setting it has (answer: it will be shown in "port
info" and you can also use "port gohome" to open it in your browser).
* For "prefix" the guide says it can be overridden on a per-port
basis, but doesn't say that there's absolutely no reason for any port
to do so; the example of Aqua apps installing into /Applications/
MacPorts is spurious; those should use ${applications_prefix}.
* Moving on a little ways, in the sections on fetching from CVS,
Subversion, GIT and Mercurial, it says these "may cause non-
reproducible builds, so it is strongly discouraged" but doesn't
elaborate. The problem there is if you fetch from HEAD; yes certainly
that will result in different builds for different users if there is
continued development in the repository. Using repository fetches in
this way is not discouraged; it's totally prohibited. You must pin
your checkout with a tag name or date (CVS) or tag url or revision or
date (Subversion); don't know what you need to do for GIT or Mercurial.
* In 4.3.4 Eliminating Phases we tell the user how to override a
phase with e.g. "build {}" but we don't tell the user not to do that
for the configure phase. Well, there is a link from there to section
5, but it's not until 5.3.7 Configure Phase Keywords that we tell the
user about "use_configure no", but we don't explain why we want users
to use that instead of "configure {}" (answer: I don't remember).
* I didn't look very hard but I don't think the Guide tries to call
out the differences between dependencies ("deps") and dependents.
This is a common source of confusion, but the sections for those two
concepts are not near one another and don't mention one another.
I'll stop for now; you get the idea. :)
_______________________________________________
macports-dev mailing list
[email protected]
http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
