Ryan Schmidt <ryandesign@macports.org> on Monday, April 9, 2007 at 2:22 AM -0800 wrote:
Redesign the whole site would definitely require planning and discussion. I feel like the documentation issue is more immediate. Right now it doesn't exist except for anyone knowledgeable enough to delve into the SVN repository.
I have tried and failed. I have a working copy of the trunk. But the documentation is not in the www directory. Instead, it appears to be in the doc directory, in docbook-xml format. To build the HTML pages apparently requires that I install the docbook-xsl port. Ok, but even then, I can't build it:
$ cd doc/guide $ make xmllint --xinclude --noout "xml/guide.xml" http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:80: element include: XInclude error : could not load xml/portfiles/details.xml, and no fallback was found http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:113: element include: XInclude error : could not load xml/project/submission.xml, and no fallback was found make: *** [check] Error 1 $
I'm not sure why it chokes on the xincludes. I've been writing in DocBook lately, but I use the XMLMind XML editor, called XXE for short. It is a WYSIWG editor. It seems to have no trouble handling the xincludes and opens it all up in the editor.
Long story short: I'm gonna read the docs using the Internet Archive from now on:
http://web.archive.org/web/20060427120406/http:// darwinports.opendarwin.org/docs/
For a start I would like to see all of the old docs dumped into the Wiki so people have access to them and some could hack on them. I've found there are parts that I would have edited as I was learning/using DarwinPorts/MacPorts.
Do we want to do that? Admittedly wikis are easier to edit. But wasn't the docbook format chosen for a reason? To those who remember: What was that reason? Does it still apply?
I think the advantages are: -A defined document structure is enforced. -Easy transformation to HTML, PDF, etc. -The format of the document is abstracted from the content. So style and format decisions do not need to be made when writing. -Format and style decisions for HTML (transformed from XML DocBook) are made separately via CSS, and so style changes are applied globally so that style consistency is enforced. But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know. I wonder if an unstructured document that has no enforcement of structure or style will be better in the end. But using an XML DocBook editor to edit and modify the current docs isn't that hard, but, similar to what Juan said, not enough time has been spent on deciding the content we want to have in our docs. If we had people contributing text of new docs, we could think about the technology to use it. But people want to be able to input text on their own into the Wiki and want to decide the content later. I wonder how well that will work for us in the end, but I've not had experience with a free-for-all wiki documentation. If it turns out an editor or supervisor for docs is needed anyway, which seems likely to me, then the advantages of a Wiki may not be as much as supposed and it may be more difficult to manage it all.
p.s. my account is messed up. I tried to update it as the macosforge site tells you but I still cannot access 'My Account' profile. And, is the Wiki open to editing by anyone with an account? I don't see any option to edit pages. The only thing I can seem to do is file tickets.
I am under the impression that anyone should be allowed to edit wiki pages. When I access wiki URLs beginning with https and log in with my macports account, there is an Edit This Page button at the bottom of each.
It is my understanding that right now only a few people can edit. I can and you can, but apparently we have higher powers than the average user. Mark