MacPorts guide & Wiki

[Juan Manuel Palacios]

On Jun 27, 2007, at 5:38 AM, Randall Wood wrote:

>
> On 27 Jun 2007, at 02:45, Ryan Schmidt wrote:
>
>>
>> On Jun 22, 2007, at 18:13, Randall Wood wrote:
>>
>>> Why not distribute the guide in a port?
>>
>> Why is that a good idea?
>
> 1)	It is eating our own dog food.

	Building MacPorts off the MacPorts Portfile is definitely eating our  
own dog food... and I can tell you it tastes good! ;-)

> Distributing it by port means that it could be bundled with the .dmg  
> installer and updated through the regular port sync ; port upgrade  
> outdated mechanism.


	Figuring out how to bundle it with the dmg is definitely a good  
thing, I think, but making it available in such a way that "sync" and  
"selfupdate" keep it up to date is probably more trouble than it's  
worth. I see some potential approaches, none of which convince me at  
all that much:

-) Create a port that fetches the xml sources from svn: you'd need a  
maybe hefty list of dependencies (to generate the html files) for  
something that's otherwise just a couple of clicks away through a web  
page;
-) Create a port that fetches the already regen'd html files: involves  
developing the regen methodology server side and making the html files  
available somewhere for fetching (our svn repo is of course an option);
	In both of these cases you'd have to come up with a versioning scheme  
for the guide in order for our regular sync/outdated/upgrade  
procedures to work with this port, but that's admittedly easy (the  
version number could simply be the regen date timestamp, yyyymmdd -- 
including hourly information as the Portfile revision if more than one  
regen takes place in single day, probably--).
-) A third and ugly alternative could be including the html guide as  
MacPorts sources, ${prefix}/share/doc/macports path (./configure's -- 
docdir option), but obviously there's a lot of Q/A to do for this  
option to be viable and smooth, and I just don't think it's worth the  
effort.

	However, if you feel motivated enough to explore any of these options  
(or any other you might have and which I'd love to hear about), then  
please do not let me stop you! The more (consistent) documentation we  
have and the more venues to access it, the better.


>
>
> 2)	There is a makefile for building the documentation from the XML  
> source already. Unfortunately it does not work right now, but I  
> think that it should be fairly trivial to get it working again.


	It does work, you just need to run the base/configure script before  
delving into the guide's Makefiles.

>
>
> 3)	The guide never migrated from the opendarwin.org servers. We  
> haven't had it on the web and there is an open ticket for the  
> ability to write static documents in wordpress on macosforge.org  
> that is still unaddressed after 9 months.[1] MacPorts controls the  
> port distribution chain in a way that we don't control the  
> macosforge.org site.


	I'll look at the ticket and make my comments, sorry for not  
addressing it in such a long time! And it's true that we don't control  
our website in the same way we control our base sources and ports  
tree, but it's also true that we've had a very good communication and  
co-existence with the entire MacOSForge community since we've been  
here, so I'm confident we'll be able to come up with a good enough  
plan to revive the guide (it hasn't been done until now simply 'cause  
no one dedicated any real time to it until now, including me).
	
>
>
>> I read Juan's message as being about encouraging people to create  
>> and update the documentation. We already have mechanisms for making  
>> it available to people -- export to HTML and put on web site.  
>> That's certainly where I would expect the documentation to live.  
>> Why do you want it suddenly distributed as a port?
>
> I don't care if it is on the website or in a port, I just want it.  
> If we can get it out in a port faster than we can get it on the site  
> then we should use a port to distribute it.


	As said above, would love to see real work initiatives materialize in  
tangible results, so do not let any of us block you in any way from  
producing them! In the mean time I'll keep on pushing for a guide web  
space.

>
> References:
>
> [1]	https://svn.macosforge.org/projects/macports/ticket/10666
>
> Randall Wood
> rhwood at mac.com
> http://shyramblings.blogspot.com


	Thank you for your interest and energy, much appreciated! Regards,...


-jmpp