I sent this to the wrong list address by mistake, so I'm sending it again. >I know that your long term goal was to integrate man pages and guide >together. But I didn't know yet that work already started on this. Now I >am looking at the man pages in XML format in doc-new/man/xml/* which are >untouched for over a year now and thus outdated as we continued to work >on them in base/doc/. For me this project looks stalled for too long.
Hi Rainer, If you can produce better docs than what I've done it doesn't matter what has already been done. I would naturally want to use the simplest method that can produce acceptable output. If you can't with the method you have proposed, then it doesn't matter if it has been stalled too long or not as long as it continues before a better plan arrives. I only raised the issue that I have already started on man pages only to say that no one should modify the guide for a new purpose without consulting the community. That would be disturbing an ongoing project that I am working on now, no matter what are one's personal judgements on what counts as stalled. It also wouldn't be necessary since if you need to demonstrate issues related to your project having to do with the guide, you could always make a copy in your branch. > >If Rainer's effort with new manpages using asciidoc is successful, we >could of course discuss the idea of migrating the Guide over to that >format as well. The problem from my perspective is that as far as I've been able to tell, what would count as success seems to have surprisingly little to do with structure or style (control over which docbook and CSS give to the current guide), and it appears from the last few messages that a commitment to using a single source has been dropped or probably soon will be too. Aside from the absolute necessity in my opinion to use a single source (eliminate duplicated effort), the main problem I see, as I've already said before, is that without a defined structure and style the docs will not be very consistent and will have no resistance to entropy in any case. >My intent with >choosing AsciiDoc as the source for the new man pages is trying to >satisfy both the need for a simple format and still being able to >integrate it into the guide. Simple formats for documentation have been >requested by Florian Ebeling some time ago [1] and I still second that >request. > >Let's just compare a little bit of the XML and AsciiDoc format. We all know asciidoc is simpler; the question is whether or not the criteria for success can be met. I looked at alternatives to XML before I started the guide (because I want the simplest solution that meets the goals too) and rejected them as not meeting my criteria for success. You've defined the success as the ability to edit bits easily and that is an easy target to hit, but has nothing to say about product quality and I think most users have greater expectations for docs than that. I think having something like NewHelpSystem is fine, but adding features doesn't mean ignoring previous design goals or dictating changes unrelated to such features. I haven't even seen where you have warned anyone or commented on the completely generic look of asciidos generated html and the lack of control for adding future format additions and changes. Are we ok with a guide that looks like Git man pages? I'm not. Is the communty satisfied with that? Or has that been discussed somewhere and I've missed it? That would be the first question I would ask, even though the other questions I've raised would still hold. If everybody is satisfied with poorly formatted and structured docs, then I really need to know that. Because I am not interested in producing documents that ugly (poorly formatted) or unsustainable (poorly structured) or the massively error-prone process of reconciling text manually between guide and man (no single doc source). In the case of the former two, it isn't worthy of a product that runs on a Mac, and in the case of the latter I just have better things to do, and I'd hope we all do. I mean no rudeness whatever, I'm just trying to get my point across. And I've said it all before and you are quite unimpressed. That is why I suppose that we should continue on parallel courses and let the community decide which is better overall. This is assuming that the community does want docs that aspire to have a good design; if not then it is time for me to retire. :) Mark _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
