Forgot to send this to the list ... >AsciiDoc still gives control over DocBook and CSS. It is still possible >to change the XSL stylesheet converting the DocBook to HTML and the CSS >is in a separate file. It is even possible to add your own DocBook >elements if that would be necessary.
Yes, but I'm just skeptical of this translation and basically assumed it won't work very well. That could be wrong, but it is the norm for translation to fail without extensive manual tweaking. >Having the man pages on the >website is a secondary goal and I had the idea only while writing the >NewHelpSystem page. The primary goal is to have a usable 'port help' >which currently is not helpful at all. ..... ... >My plan is not to offer the Guide as man pages. This is mainly new >content describing the various options of the port commands. Here is the problem. This will mean duplicate information and instructions in the man pages and in the guide. I think this is unsupportable. That is why I stopped writing content to work out a strategy to merge in man pages and manage the content as a whole. rather than provide similar information in two places and why the guide was delayed when I was on the task. It is impossible to have accuracy without a single source, and I am confident that no one here has the time or inclination to reconcile two sets of similar text. There are doc tickets that say "need to merge web site install section with guide install section" that illustrate how people react to multiple sources. Bottom line is that the sources for the man pages need to be the bases for the relevant guide sections (currently the reference section) on a given topic. The guide and the man pages need to be designed together, and that is what was being done. I know development stalled, but that was not for lack of interest. >And as we see in the guide, we are already applying customizations by >hacks. This is a) a sed expression to insert links to the headline >anchors b) a Tcl script to insert the TOC into each page for the chunked >version. Probably it would also be possible to do this with XSLT, but >it's probably too complicated. So there is the point in "having control"? Yes I know is is hacky. The fact is I don't know that using XML source is the best way to do on the man pages. It could be that asiidoc is a better way in the end. I am not committed to any technology per se, despite the impression I may have given by defending DocBook. If asciidoc can be made to do the job I'm fine with that, I am just skeptical. I would be entirely open to using something else as long as the principles I think that are necessary for good docs overall are maintained, and the principle of treating the guide and man pages (and other docs) comprehensively (accomplished mostly by using a single source) is one of them. It might well be that asciidoc has a place, but I'm not sure. But look, even the GNU coding standards (sect 6.9) show that man pages are secondary and the problems that can result from man page contributions: http://www.gnu.org/prep/standards/standards.html and multiple sources. I know it may sound ungrateful to question work before is is done, and I appreciate your willingness to put in time improving the usability of MacPorts, but it isn't a crazy idea to hash some things out up front so there won't be any bitterness later on. I"m not opposed at all to anyone's work, but how would you like it if I waited until you got something working before I jump in with my concerns? That would wasting your time (assuming my arguments had merit and were persuasive to the community) and be pretty rude. So don't think my early objections are trying to stop you from doing beta work or whatever. >Please do not take this discussion too personal. I appreciate your work >and I am looking forward for further contributions by you. It is >probably my fault that I quietly added this wiki page describing my plan >without any announcement on the mailing list. But I was not going to >hold a speech promoting AsciiDoc without having tried if it would work >at all. I also didn't want to do this all in private and come up with a >finished solution in a few months. Rather I am doing everything in >public so others can chime in about it and I can get some feedback if >this concept of 'port help' would be accepted at all. I don't think I am taking it personally. I think the main difference here is that I take a content writer's perspective, whereas I think you are taking a developer's perspective. I am all about content and experience overall, and that structure and style only matters as far as it support the goals of knowledge management (content) and usability (experience). If asciidoc does it better then I could easily support that. I think I've shown that my concerns are on principles, right or wrong. I think your point of view is all about delivery, and not so much what gets delivered if I may say so. And I'm not sure you are aware that you seem to be ignoring my rewritten man pages that contain extensive content that is not in the current man pages. I was confused by the wandering among several topics related to asciidoc advocacy recently and I didn't realize you might be doing that until just now. It seems to me you are doing what is normally called "context sensitive help", and I think that is another reason to consider the docs as a whole. Maybe there is a way that we could work together on this. Is there a decent way to have a particular 'port help foo' command spit out a section of a man page? Or it could be that each port command could be treated as a separate topic thatt get included in a file of similar topics together as man pages, which could then be included in the guide one way or another. If they are written with their inclusion with the guide in mind that would be fine. I just don't think it is good to write them based on the needs of the delivery system, the outdated man pages, or anything other than a comprehensive point of view on the docs as a whole. Mark _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
