The Guide - again

[Ryan Schmidt]

On Mar 9, 2009, at 20:59, markd at macports.org 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. :)