The Guide - again

[markd at macports.org]

>>> 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. :)

These are all good points.  I don't just get the idea, I know the idea. 
:)  I know there are many weaknesses in it, and for the most part it
really hasn't even been proofread yet.  Like I said, I see this process in
phases and the fact is that these elements are a part of refinement
process, which is not the one we're in right now.  We're still in the
throwing in large chunks phase, though it might not seem like it because
of the lack of activity last year.  But throwing in large chunks is what
is on my todo list right now and what was happening before the pause in
activity at the end of last year.

And looking at other examples we'd like to emulate is very good, and I
appreciate you referencing the other docs you did.  One reminded me that
I've wanted to create a sweet graphic in it to make the parts of MacPorts
clear.  It wouldn't take long to do.

But the use_configure issue is a classic case of how not to use
documentation.  Documentation can't cover up glaring design flaws.  The
documentation and product should be thought of as a whole.  use_configure
is a glaring inconsistency and either needs to be removed or use_build,
use_destroot, etc added.  I'd prefer the former since the latter seems
ugly, and "configure {}" seems no easier to remember in any way than
"use_configure  no", in fact it is harder and more error prone.  Better to
fix the product.  Documenting inconsistent product behavior is putting
lipstick on a pig.  

In fact, I wonder why some keywords have dot separaters for words and some
have periods generally.  At least I don't know the pattern for this if
there is one.

Mark