Evening everyone! I am glad to announce that we've finally finished the 1.5.0 edition of MacPorts, readily available through all our regular distribution means: -) binary installer for both 10.4 (Universal) and 10.3, http:// svn.macports.org/repository/macports/downloads/MacPorts-1.5.0/ -) source tarballs, both gz and bz2 formats, same location as above; -) selfupdate. Of all the features and bug fixes in the changelog quoted below, I'd like to point out two in particular: 1) The MacPorts project no longer mixes its old DarwinPorts name with the new one at any level, whether that is in chosen installation paths, file names, strings we output to the user and many more things. This implies that upon installing 1.5.0 several things in a standard MacPorts installation will silently change to new naming and installation locations, as thoroughly detailed in the Wiki page that tracked this work as it was being developed: http://trac.macports.org/ projects/macports/wiki/MacPortsRenaming. Please read it carefully before getting scared about your configuration files or other stuff being missing ;-) 2) Even though still not complete, extensive work on the generation of rpm's off MacPorts Portfiles has pushed forward our ability to generate real binary packages, improving both the building of the rpm tool itself on Mac OS X and the "rpm" MacPorts target (renamed from "rpmpackage") that creates the corresponding rpm files/packages. These packages still need to be generated by users off their own MacPorts installations ("port rpm <port>"), and flawless functionality for each of them is still not guaranteed, unfortunately. For instance, one long standing shortcoming still with us is that rpm installed software (even if the package is generated through MacPorts) is separate from MacPorts installed software, they are still two different universes that don't talk to each other even if installed into the same /opt/local prefix. However, strong developer momentum on the packaging front raises our hope that the goal of providing fully working and ironed out binary packages will be reached eventually! So, without much further ado, enjoy MacPorts 1.5.0! Biggest thanks to all those who worked to produce this solid release, kudos! Regards,... -jmpp PS: Full 1.5.0 ChangeLog following: Release 1.5 (09-July-2007 tagged at r26818 by jmpp): - Many documentation updates and improvements, mostly thanks to Maun Suang and Brian Campbell who both started work on both improving our man pages and reviving the long forgotten MacPorts official guide, now nightly regen'd on an automated basis and hosted at a temporary location, http://geeklair.net/ macports_guide/, all thanks to Daniel J. Luke (dluke). - Improve built-in "daemondo" program logging (jberry r26537 & r26569). - rpm target now knows how to also build universal packages if requested (afb r26470). - The "rpmpackage" target was renamed to "rpm", and a new target "srpm" added that allows packaging a Portfile (and files/distfiles) up as a source package. Upgraded RPM to version 4.4.9 and changed OpenDarwin/ DarwinPorts to MacPorts. The default build location is now ${prefix}/src/macports instead of ${prefix}/src/apple (jmpp & afb in r26465, r26496, r26536, r26543). - Fixed a potential crasher in the delete command (ticket #12149, eridius r26397). - 'port delete --work' now removes $portbuiltpath instead of $workpath, effectively prunning empty dirs that up until now were left behind in the build directory (jmpp r26394). - gnustep portgroup for gnustep-make-2.0 (yves r26266). - Adding backwards compatibility glue for clients of the public (darwin|mac)ports1.0 API that use now deprecated procs naming (DarwinPorts namespace) (jmpp r26392). - Merged the dp2mp-move branch into trunk to finally move away from all DarwinPorts related strings and conventions both internally and externally, implying big changes in MacPorts pathnames with respect to user visible stuff. Read http://trac.macports.org/projects/macports/wiki/ MacPortsRenaming and http://trac.macports.org/projects/macports/log/branches/dp2mp- move/base for more full details and information (jmpp r26177). - Fix livecheck to properly de-escape livecheck.url (eridius r26041). - Add warning when it looks like PortIndex file is corrupt (eridius r26040). - Make portindex use stderr for errors (eridius r26038, ticket #11585). - Fix port variants calculation to properly account for negated variants and to detect problems between required and negated variants (ticket #11920, eridius r26036, patch by gwhitney). - Add global methods lpush, lpop, lshift, and lunshift. Works similar to lappend (in fact lpush is just lappend) and do what they sound like. Also add ldindex. Works like lindex, but deletes the element from the list. Documented in portfile.7 (eridius r26034). - Add global methods try and throw. Implemented based on the specification in TIP #89. Documented in portfile.7 (eridius r25979). - Handle encodings properly now. All Portfiles and .conf files are assumed to be utf-8, and reading them or calling portindex(1) should now work the same on all locales (ticket #11978, eridius r25975). - Add support for decoding of obscured maintainer addresses. We support two types of obscured addresses in Portfile maintainers field: (1) username ==> implies username@macports.org (2) subdomain.tld:username ==> implies username@subdomain.tld These are unobscured by port info, and by port submit during the submission process, but are left obscured in the Portfile to avoid accidental disclosure. (jberry r25795). - Update port.1 to reflect what "port dependents" really does (markd r25787, ticket #11898). - Distinguish a pseudo portname that evaluates to nothing from no arguments at all, improving behavior of 'installed', 'active', 'list', and 'search' pseudo portnames. (jberry in r25789, ticket #10674). - Bugfix startup item generation so that launchd.plists are disabled by default, as we claim they are in our documentation. (jberry r25785). - Update adduser/addgroup to use dscl instead of niutil. Also add support for realname key in addgroup (ticket #11012, eridius r25586). - Make a correction to port(1)'s determination of whether or not a port has been updated by making it compare ${version} and then $ {revision} rather than a single comparison of the compound ${version}_$ {revision}; the latter reports 2.01_2 to be newer than 2.01.01a25_0 because, at the fifth character, `_' comes after `.' in ASCII lexicographic order. (boeyms in r25310)
Juan Manuel Palacios <jmpp@macports.org> on Monday, July 9, 2007 at 11:54 PM -0800 wrote:
2) Even though still not complete, extensive work on the generation of rpm's off MacPorts Portfiles has pushed forward our ability to generate real binary packages, improving both the building of the rpm tool itself on Mac OS X and the "rpm" MacPorts target (renamed from "rpmpackage") that creates the corresponding rpm files/packages. These packages still need to be generated by users off their own MacPorts installations ("port rpm <port>"), and flawless functionality for each of them is still not guaranteed, unfortunately. For instance, one long standing shortcoming still with us is that rpm installed software (even if the package is generated through MacPorts) is separate from MacPorts installed software, they are still two different universes that don't talk to each other even if installed into the same /opt/local prefix. However, strong developer momentum on the packaging front raises our hope that the goal of providing fully working and ironed out binary packages will be reached eventually!
I am progressing on the new Guide. I mispoke when I called the new Guide "minimalist", because that implies stuff will be left out. I only intended to streamline and rewrite it (some explanations were verbose and redundant) but leave no material out. I just added all the sections that I think need to be in it and I inserted the contents of "MacPorts Internals" stuff from the old guide too. Shouldn't be long now that all the data will be mined from the old guide. Not that the work is over since improvments will still be needed, but at least we can look forward to those rather than looking backwards and trying to capture what used to be. http://homepage.mac.com/duling/macports/guide.html Comments still welcome on the Guide so far. It needs some color css work and other css formatting, but I'm focusing on content and readability. I don't feel competant to write Section 7, "Packaging Ports into Binaries". Can anyone who understands the packaging process throw some text at me on this topic? Doesn't have to be much or pretty, I can rewrite it but I just something more or less technically accurate to start with. Or point me to a similar section in another package manager if that is possible. I'm just not that familiar with the whole topic and the manpage doesn't say that much. Mark
markd wrote:
http://homepage.mac.com/duling/macports/guide.html
Comments still welcome on the Guide so far. It needs some color css work and other css formatting, but I'm focusing on content and readability.
There are some common typos in it like "OS X" (Mac OS X) and "Xwindows" (X Window System) and it should probably be less Apple/Mac OS X centric (i.e. should mention explicitly that 2.1-2.5 applies to Mac OS X, and say something instead of "Apple-supplied" - like vendor-supplied, etc etc...) It would also be nice if it could mention "open source and free software", instead of just saying "open source Unix software" and not mentioning GNU ? This is IMHO also another reason why it is important to get License metadata into the ports, as it is now you'll have to dig through homepages/licenses. You can look at the old guide for some hints, it uses "third party software" and has much more info on the common heritage with the BSD Ports/collections. A "MacPorts for people used to *BSD Ports" section might even be a good idea. Besides regular Mac OS X, MacPorts is also usable on FreeBSD (with GNUstep).
I don't feel competant to write Section 7, "Packaging Ports into Binaries". Can anyone who understands the packaging process throw some text at me on this topic? Doesn't have to be much or pretty, I can rewrite it but I just something more or less technically accurate to start with. Or point me to a similar section in another package manager if that is possible. I'm just not that familiar with the whole topic and the manpage doesn't say that much.
I will try to be of some assistance about those, we can take either in the regular guide xml or if you're doing some kind of parallel guide we can discuss it here on these mailing lists or on some Wiki page... As it is now we have two kinds of binaries: ARCHIVES (.tgz, .tbz, etc) and PACKAGES (.pkg, .rpm, etc). Eventually these might both be able to use the same XAR archive, but as of now they're still separate... The archives are created with "port archive" or by enabling archivemode. They can (confusingly!) be found under /opt/local/var/macports/packages with subdirectories for each platform (e.g. darwin) and arch (e.g. i386) The packages are created with something like "port pkg" or "port rpm" and are found in either the work directory or /opt/local/src/macports. Since .pkg is a dir bundle, it is converted to one file with "port dmg". The main differences is that the archives are used within the port system, to avoid having to rebuild a port from source, and that the packages are used outside the port system, without even needing MacPorts installed. Besides the binary packages, we also have source packages. These consist of the Portfile and all needed files/ (patches and other supporting files), and they come in either ".portpkg" (XAR) or ".nosrc.rpm" (SRPM) flavors. Normally there is not much need to use source packages, since the binary packages can be built directly from the ports tree (whether rsync or svn) but they are useful for port submissions or for storage of older versions. In order to build a new binary from a source package, all the corresponding distfiles are also needed. Normally these are only kept around as checksums, but can be mirrored locally - or even included in the case of ".src.rpm". When building packages, all dependencies must be installed from ports or archives - installations made from packages do not help and must be redone. This is because the binary packages are *not* registered within MacPorts. Hopefully that should be enough to start, and let me know if I am mistaken... --anders
Anders F Björklund <afb@macports.org> on Tuesday, July 10, 2007 at 5:41 AM -0800 wrote:
There are some common typos in it like "OS X" (Mac OS X) and "Xwindows" (X Window System) and it should probably be less Apple/Mac OS X centric (i.e. should mention explicitly that 2.1-2.5 applies to Mac OS X, and say something instead of "Apple-supplied" - like vendor-supplied, etc etc...)
It would also be nice if it could mention "open source and free software", instead of just saying "open source Unix software" and not mentioning GNU ? This is IMHO also another reason why it is important to get License metadata into the ports, as it is now you'll have to dig through homepages/licenses.
You can look at the old guide for some hints, it uses "third party software" and has much more info on the common heritage with the BSD Ports/collections. A "MacPorts for people used to *BSD Ports" section might even be a good idea. Besides regular Mac OS X, MacPorts is also usable on FreeBSD (with GNUstep).
All good points. I haven't yet got to that level of detail yet, but I agree with you it needs to be done. I'll hang onto these suggestions and address them the best I can after getting all the raw data I can from the old guide.
I will try to be of some assistance about those, we can take either in the regular guide xml or if you're doing some kind of parallel guide we can discuss it here on these mailing lists or on some Wiki page...
As it is now we have two kinds of binaries: ARCHIVES (.tgz, .tbz, etc) and PACKAGES (.pkg, .rpm, etc). Eventually these might both be able to use the same XAR archive, but as of now they're still separate...
The archives are created with "port archive" or by enabling archivemode. They can (confusingly!) be found under /opt/local/var/macports/packages with subdirectories for each platform (e.g. darwin) and arch (e.g. i386)
The packages are created with something like "port pkg" or "port rpm" and are found in either the work directory or /opt/local/src/macports. Since .pkg is a dir bundle, it is converted to one file with "port dmg".
The main differences is that the archives are used within the port system, to avoid having to rebuild a port from source, and that the packages are used outside the port system, without even needing MacPorts installed.
Besides the binary packages, we also have source packages. These consist of the Portfile and all needed files/ (patches and other supporting files), and they come in either ".portpkg" (XAR) or ".nosrc.rpm" (SRPM) flavors.
Normally there is not much need to use source packages, since the binary packages can be built directly from the ports tree (whether rsync or svn) but they are useful for port submissions or for storage of older versions.
In order to build a new binary from a source package, all the corresponding distfiles are also needed. Normally these are only kept around as checksums, but can be mirrored locally - or even included in the case of ".src.rpm".
When building packages, all dependencies must be installed from ports or archives - installations made from packages do not help and must be redone. This is because the binary packages are *not* registered within MacPorts.
Hopefully that should be enough to start, and let me know if I am mistaken...
I'll have to look at your descriptions later tonight (I hope) and write something up and send it back to the list for more peer review. BTW, I don't want a parallel guide; I'd like to get the new one replaced and I'm willing to go take whatever suggestions, contributions, or changes the community thinks necessary to make a new guide official. I just think the modifying the old guide is too difficult if we want very much improvement. Thanks very much for your help! Mark
On Jul 10, 2007, at 07:41, Anders F Björklund wrote:
markd wrote:
http://homepage.mac.com/duling/macports/guide.html
Comments still welcome on the Guide so far. It needs some color css work and other css formatting, but I'm focusing on content and readability.
There are some common typos in it like "OS X" (Mac OS X) and "Xwindows" (X Window System) and it should probably be less Apple/Mac OS X centric (i.e. should mention explicitly that 2.1-2.5 applies to Mac OS X, and say something instead of "Apple-supplied" - like vendor-supplied, etc etc...)
[snip] I would counter that being Apple- and Mac-centric is a good thing. The project name was deliberately changed from DarwinPorts to MacPorts to emphasize the fact that it's designed for Mac users. MacPorts has so far not been so easy for the typical non-UNIX-geek Mac user to understand, so I would consider being Mac-specific in the documentation to be a good thing. I'm not sure if anything non-Mac- centric needs to be said in the documentation, other than at most a sentence in the introduction stating that the project is designed for Macs, that it may work on other OSes, but that this is not guaranteed. I haven't actually looked at the guide yet, but wanted to make the above comments anyway.
Ryan Schmidt wrote:
I would counter that being Apple- and Mac-centric is a good thing. The project name was deliberately changed from DarwinPorts to MacPorts to emphasize the fact that it's designed for Mac users. MacPorts has so far not been so easy for the typical non-UNIX-geek Mac user to understand, so I would consider being Mac-specific in the documentation to be a good thing. I'm not sure if anything non-Mac-centric needs to be said in the documentation, other than at most a sentence in the introduction stating that the project is designed for Macs, that it may work on other OSes, but that this is not guaranteed.
There is a difference between not actively supporting use on other platforms, and actively discouraging using the product on other platforms (whether by code or by words)... Don't get me wrong here, I don't think there is anything wrong whatsoever with using Apple and Mac terms to describe how you install MacPorts on Apple Mac OS X. But everywhere? Nah.
I haven't actually looked at the guide yet, but wanted to make the above comments anyway.
Please do then, we're talking about something minor like changing "Installing MacPorts" to "Installing MacPorts on Mac OS X" and avoiding limiting the entire system to just the Apple Macs. Don't see how "Mac OS X and other platforms" or "Apple or other vendors" would hurt anything. Unless the project clearly defines that it will remove all old code for Darwin and for FreeBSD. --anders
Anders F Björklund <afb@macports.org> on Tuesday, July 10, 2007 at 2:32 PM -0800 wrote:
Don't get me wrong here, I don't think there is anything wrong whatsoever with using Apple and Mac terms to describe how you install MacPorts on Apple Mac OS X. But everywhere? Nah.
we're talking about something minor like changing "Installing MacPorts" to "Installing MacPorts on Mac OS X" and avoiding limiting the entire system to just the Apple Macs.
Don't see how "Mac OS X and other platforms" or "Apple or other vendors" would hurt anything. Unless the project clearly defines that it will remove all old code for Darwin and for FreeBSD.
I think that writing the guide so it is has enough generality to accomodate other operating systems is a good idea; it just wasn't one of the major things in my mind since my main goal to start with was/is conceptual clarity of the overall system. For the OS question, I woulld like to use this approach: 1) Make the guide as platform agnostic as possible without confusing OS X users. 2) Mention what alternative OSs are likely to work in the introduction. 3) If alternative OS instructions are desired or needed, put them in a doc "sandbox" (separate guide section, or MP wiki, etc). If we stick to that philosophy I think it would minimize how much we need to revisit the "do these guide mods/additions make sense for OS X and BSD" questions as time goes on. And leave the question of what alternative OSs we support to the people writing and contributing to the code over time. Thoughts are welcome. Mark
On 10/07/2007, at 17:46, markd@macports.org wrote:
Comments still welcome on the Guide so far.
I haven't been through it in detail, but it looks good to me. I haven't thought too clearly about what, if anything, should become of the old guide (I don't know if a separate technical reference is warranted, which seems to be what the old guide leans towards). Perhaps we can post them somewhere and solicit feedback from users as to what they find easiest to understand and use, and what they think ought to be included or restructured. As for the source of your guide, which I understand is a DocBook article, would be able to put it into the doc/ part of the repository so that we can look at it? I understand if you'd like to hang onto control of it yourself (saves me some work, for a start :P), but I think it'd be helpful if the source was somewhere that all those interested in the working on documentation could see it. Kind regards, Maun Suang -- Boey Maun Suang (Boey is my surname) Email: boeyms at macports dot org
Boey Maun Suang <boeyms@macports.org> on Thursday, July 12, 2007 at 10:16 AM -0800 wrote:
Comments still welcome on the Guide so far.
I haven't been through it in detail, but it looks good to me. I haven't thought too clearly about what, if anything, should become of the old guide (I don't know if a separate technical reference is warranted, which seems to be what the old guide leans towards). Perhaps we can post them somewhere and solicit feedback from users as to what they find easiest to understand and use, and what they think ought to be included or restructured.
I really wanted the new guide to serve as technical reference also, at least for now. I wanted the "Portfile Reference" section to be more or less exhaustive. If that should turn out too large then it could be split out into a separate reference, but I'm not sure it will be that large. My two goals for he new guide was 1) better organization, and 2) more or less exhaustive "Using MacPorts" and "Portfile Reference" sections. The latter to give us a place to stick all the helpful information about keywords and commands that we exchange on the list now, and often forget. Those things should go in the guide but the old guide had no structure to contain them, and I don't think a FAQ is adequate.
As for the source of your guide, which I understand is a DocBook article, would be able to put it into the doc/ part of the repository so that we can look at it? I understand if you'd like to hang onto control of it yourself (saves me some work, for a start :P), but I think it'd be helpful if the source was somewhere that all those interested in the working on documentation could see it.
Here's where I need some advice. I did the new guide as an "article" and in one XML file because that was more familiar to me. Should I switch to a "book" and/or split the XML into multiple files? Anders has reminded me that the copyright information frm the old guide needs to be added back in and I haven't got there yet. Other than that those questions I'm willing to commit it to svn. And I can't fill in the reference sections fully by myself anyway so it does need to be committed very soon. Let me know your thoughts on that. Mark
Couple of quick comments, I see that thankfully you guys already have a lot of the details sorted out and the ball is rolling! On Jul 12, 2007, at 2:30 PM, markd@macports.org wrote:
Boey Maun Suang <boeyms@macports.org> on Thursday, July 12, 2007 at 10:16 AM -0800 wrote:
Comments still welcome on the Guide so far.
I haven't been through it in detail, but it looks good to me. I haven't thought too clearly about what, if anything, should become of the old guide (I don't know if a separate technical reference is warranted, which seems to be what the old guide leans towards). Perhaps we can post them somewhere and solicit feedback from users as to what they find easiest to understand and use, and what they think ought to be included or restructured.
I really wanted the new guide to serve as technical reference also, at least for now. I wanted the "Portfile Reference" section to be more or less exhaustive. If that should turn out too large then it could be split out into a separate reference, but I'm not sure it will be that large.
My two goals for he new guide was 1) better organization, and 2) more or less exhaustive "Using MacPorts" and "Portfile Reference" sections. The latter to give us a place to stick all the helpful information about keywords and commands that we exchange on the list now, and often forget. Those things should go in the guide but the old guide had no structure to contain them, and I don't think a FAQ is adequate.
First off, and even if it's just a first draft that we can improve as we learn from experience, I'd like to see a single all- encompassing guide too, with a "users oriented" first section and a "developers" section in which we can put all the Portfile reference stuff and others not geared for regular users. If this proves to be hard to manage and a lot of voices raise up asking for a "simple and short user reference", I'm figuring we can always take the contents of the rewritten guide and split them up in two.
As for the source of your guide, which I understand is a DocBook article, would be able to put it into the doc/ part of the repository so that we can look at it? I understand if you'd like to hang onto control of it yourself (saves me some work, for a start :P), but I think it'd be helpful if the source was somewhere that all those interested in the working on documentation could see it.
Here's where I need some advice. I did the new guide as an "article" and in one XML file because that was more familiar to me. Should I switch to a "book" and/or split the XML into multiple files? Anders has reminded me that the copyright information frm the old guide needs to be added back in and I haven't got there yet. Other than that those questions I'm willing to commit it to svn. And I can't fill in the reference sections fully by myself anyway so it does need to be committed very soon. Let me know your thoughts on that.
We spoke about committing to svn and you expressed your thoughts and concerns about it, but I didn't manage to reply at the moment due to a lack of time. In a nutshell, I'd really love to see your work in our tree so that all those willing to contribute can do it in a more timely fashion (I know I would have already contributed three or four fixes if I had access to the sources ;-). But I understand that since you're not amending what we have but actually rewriting it, you prefer to keep from committing until your sources become an actual drop in replacement for what's already there. So how's the following: you write up the new guide up to the point where it can replace to a good extent what we have, even leaving empty certain sections/areas if you have to because you don't have enough information to write it up on your own, and you commit that? Once that's in all of us can dive in and help you complete it. I'm even thinking that for the sections you can't rewrite, but what's in the old guide suffices for them to whatever extent, you can simply copy & paste that into the new sources and write up a marker saying "THIS IS OLD, NEEDS REWRITING!" for contributors to notice. More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Mark
So, what do you guys say? Does this sound like a good protocol? Regards,... -jmpp
Juan Manuel Palacios <jmpp@macports.org> on Thursday, July 12, 2007 at 5:24 PM -0800 wrote:
First off, and even if it's just a first draft that we can improve as we learn from experience, I'd like to see a single all- encompassing guide too, with a "users oriented" first section and a "developers" section in which we can put all the Portfile reference stuff and others not geared for regular users. If this proves to be hard to manage and a lot of voices raise up asking for a "simple and short user reference", I'm figuring we can always take the contents of the rewritten guide and split them up in two.
My thoughts exactly. Though I did not end up dividing cleanly into users/developers parts, I personally think that since even newbies these days sometimes ask "How do I modify a Portile?", that the guide is better sectioned functionally according MacPorts itself, rather than by hypothetical types of users. But still, more or less the first part is the "using" part, the middle part tends towards development, and the end is pretty advanced stuff. Not clear lines, but I think the sections make the guide fairly intuitive nonetheless. At least I hope, and others are certainly free to disagree or suggest changes.
We spoke about committing to svn and you expressed your thoughts and concerns about it, but I didn't manage to reply at the moment due to a lack of time. In a nutshell, I'd really love to see your work in our tree so that all those willing to contribute can do it in a more timely fashion (I know I would have already contributed three or four fixes if I had access to the sources ;-). But I understand that since you're not amending what we have but actually rewriting it, you prefer to keep from committing until your sources become an actual drop in replacement for what's already there.
So how's the following: you write up the new guide up to the point where it can replace to a good extent what we have, even leaving empty certain sections/areas if you have to because you don't have enough information to write it up on your own, and you commit that? Once that's in all of us can dive in and help you complete it. I'm even thinking that for the sections you can't rewrite, but what's in the old guide suffices for them to whatever extent, you can simply copy & paste that into the new sources and write up a marker saying "THIS IS OLD, NEEDS REWRITING!" for contributors to notice.
More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Sounds like a decent plan to me. I just committed what I have so far. xml/newguide.xml http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/xml/new... resources/newdocbook.css http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/resourc... Hack away! Needs work in the reference sections, among others. 6.2 and 6.3 have placeholders for keywords and Tcl primitives respectively. Full comments in the svn checkout logs. See the the updated copy with a slightly different stylesheet at my .mac page for those wanting a peek at the draft of the new guide. Colors are awful! You have been warned! http://homepage.mac.com/duling/macports/guide.html Mark
Mark wrote:
More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Sounds like a decent plan to me. I just committed what I have so far.
xml/newguide.xml http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/ xml/newguide.xml?rev=26949
resources/newdocbook.css http://trac.macosforge.org/projects/macports/browser/trunk/doc/guide/ resources/newdocbook.css?rev=26950
Hack away! Needs work in the reference sections, among others. 6.2 and 6.3 have placeholders for keywords and Tcl primitives respectively. Full comments in the svn checkout logs.
I committed a new target ("make new") to the guide Makefile, so that one can generate the "new" html (it uses the docbook XSL and generates XHTML) Also added the missing copyright information, which unfortunately was left out of your "Minimalist Guide". It also needs a documentation license added later, so that the guide can be distributed along with the software. Probably some Open Content license, to match the Open Source BSD license ? Will leave the rest of the updates to you guys, and use the Trac Tickets.
See the the updated copy with a slightly different stylesheet at my .mac page for those wanting a peek at the draft of the new guide. Colors are awful! You have been warned!
It just uses the DarwinPorts color scheme still, so it's a bit too "cute"... http://web.archive.org/web/20070103015001/http:// darwinports.opendarwin.org/ Probably it can be redone along with the main MacPorts website <hint hint>. As in: better to do a proper redesign of the entire MacPorts "brand" later ? Hopefully there are lots of web designers wanting to help the project ? :-) --anders
Thanks for the great documentation progress guys! I cleaned up some of our documentation tickets up on trac: *) renamed the "doc" component to "guide" *) relocated most of the old doc component tickets I could find to more appropriate components, of course leaving there the ones that belong. What I intended with these changes is the following: we now have a documentation milestone and two documentation related components, "base" and "guide", the former for stuff like our man pages (and maybe doxygen like in source documentation in the future) and the latter being self explanatory; any new documentation related tickets should be filed under the appropriate milestone and its component flagged accordingly. I believe this split gives us nicely, fine- grained enough (but not too much) organizational choices. Please feel free to suggest something different if you believe this will not suite us (but if you do, you're gonna have to help me through trac adapting tickets as needed! :-P) So, moving forward, I skimmed over the new guide sources and filed my first ticket: http://trac.macports.org/projects/macports/ticket/12284 Guide Masters, start your engines! Once the new guide properly replaces the old one we're gonna have to think about removing the latter and adapting the Makefile targets and GuideRegen.sh script to build the new one. Mark, how are you currently building the new guide? Any automation put into that? (hint: base/portmgr/GuideRegen.sh) I'm hoping you guys can give us a heads-up when you believe we're ready to flip the coin and make this change (I'm figuring at that point the trunk/doc/guide/xml/newguide.xml file will have to be renamed to something more appropriate). Regards,... -jmpp PS: I made markd@macports.org default owner for tickets under the "guide" component. Please advice if you'd like to have that changed to something else, but trac allows only a single owner per component and no other way of informing there's more than one in charge for a particular one, like Maun Suang and Mark for this case, as I had in mind. On Jul 13, 2007, at 8:20 AM, Anders F Björklund wrote:
Mark wrote:
More over, we can all agree to nominate Maun Suang and you "Guide Masters": rather than simply diving in and committing patches to the sources in svn, we instead upload them to tickets in the "Documentation" milestone and you guys, governing that milestone, review them and decide when/how to commit them, rewriting them if need be.
Sounds like a decent plan to me. I just committed what I have so far.
xml/newguide.xml http://trac.macosforge.org/projects/macports/browser/trunk/doc/ guide/xml/newguide.xml?rev=26949
resources/newdocbook.css http://trac.macosforge.org/projects/macports/browser/trunk/doc/ guide/resources/newdocbook.css?rev=26950
Hack away! Needs work in the reference sections, among others. 6.2 and 6.3 have placeholders for keywords and Tcl primitives respectively. Full comments in the svn checkout logs.
I committed a new target ("make new") to the guide Makefile, so that one can generate the "new" html (it uses the docbook XSL and generates XHTML)
Also added the missing copyright information, which unfortunately was left out of your "Minimalist Guide". It also needs a documentation license added later, so that the guide can be distributed along with the software. Probably some Open Content license, to match the Open Source BSD license ?
Will leave the rest of the updates to you guys, and use the Trac Tickets.
See the the updated copy with a slightly different stylesheet at my .mac page for those wanting a peek at the draft of the new guide. Colors are awful! You have been warned!
It just uses the DarwinPorts color scheme still, so it's a bit too "cute"... http://web.archive.org/web/20070103015001/http:// darwinports.opendarwin.org/ Probably it can be redone along with the main MacPorts website <hint hint>. As in: better to do a proper redesign of the entire MacPorts "brand" later ?
Hopefully there are lots of web designers wanting to help the project ? :-)
--anders
_______________________________________________ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo/macports-dev
Juan Manuel Palacios <jmpp@macports.org> on Friday, July 13, 2007 at 10:23 AM -0800 wrote:
I cleaned up some of our documentation tickets up on trac:
*) renamed the "doc" component to "guide" *) relocated most of the old doc component tickets I could find to more appropriate components, of course leaving there the ones that belong.
What I intended with these changes is the following: we now have a documentation milestone and two documentation related components, "base" and "guide", the former for stuff like our man pages (and maybe doxygen like in source documentation in the future) and the latter being self explanatory; any new documentation related tickets should be filed under the appropriate milestone and its component flagged accordingly. I believe this split gives us nicely, fine- grained enough (but not too much) organizational choices. Please feel free to suggest something different if you believe this will not suite us (but if you do, you're gonna have to help me through trac adapting tickets as needed! :-P)
These changes sound sensible to me.
So, moving forward, I skimmed over the new guide sources and filed my first ticket:
http://trac.macports.org/projects/macports/ticket/12284
Guide Masters, start your engines!
I just committed it. Thanks!
Once the new guide properly replaces the old one we're gonna have to think about removing the latter and adapting the Makefile targets and GuideRegen.sh script to build the new one. Mark, how are you currently building the new guide? Any automation put into that? (hint: base/portmgr/GuideRegen.sh)
No automation yet. I'm using a GUI tranform tool, XFC from XMlmind. I'm a poor excuse for a geek. :) I'm going to examine the GuideRegen.sh to learn how to do it via terminal commands.
I'm hoping you guys can give us a heads-up when you believe we're ready to flip the coin and make this change (I'm figuring at that point the trunk/doc/guide/xml/newguide.xml file will have to be renamed to something more appropriate).
I'll be interested in seeing: 1) the response from the community as far as how usable they think it is. 2) whether developers are interested in populating the reference sections so that the guide becomes a true reference guide. And we desperately need someone to give the sylesheet some CSS love and make it blend with the overall MacPorts site. I really want to keep the TOC sidebar; that's my baby, but the colors and other look/feel items need someone less artistically challenged. Mark
On Jul 10, 2007, at 12:46 AM, markd@macports.org wrote:
Comments still welcome on the Guide so far.
Hey guys, I've been busy lately on some real work, but I wanted to pass along my support for the work you're doing on the documentation. Nice efforts! James
participants (7)
-
Anders F Björklund
-
Boey Maun Suang
-
Ernest Prabhakar
-
James Berry
-
Juan Manuel Palacios
-
markd＠macports.org
-
Ryan Schmidt