Website redesign (was Re: Please clear up DarwinPort/MacPorts confusion)

[markd at macports.org]

Ryan Schmidt <ryandesign at 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