[email protected] wrote: > 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.
As I already explained, I do not plan to replace the current guide with the NewHelpSystem. My effort is to create "hands-on" help available by using the 'port help' command. And I am also not doing this on trunk, I created a new branch for it. If it does not work out as expected, then we can still throw it away and start something else. > 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. 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. > 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. I don't see how you would apply the style and structure of the Guide being a website to man pages in Terminal. 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. I made a call for contributions on macports-users before about writing more helpful strings for the current implementation, but nobody seems to be interested. So why should I not be allowed to do something about it if nobody else cares? And as it is me doing the work, I am going to do it in a way I like. > [...] > 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. I didn't warn anybody because your expectations are simply not true. As AsciiDoc uses DocBook as intermediate format, we can apply the same customizations as to any document directly written in DocBook. This includes changing XSLT and CSS. 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"? It was me who lately digged through the XSLT to add attribute customizations to the single-page and the chunked versions and I also added links to switch between them. And how should I ask the community before I have anything to show? A HTML version of the man pages would not have to look exactly like the ones on the Git homepage. We can still apply custom CSS or even custom XSLT. Be aware that AsciiDoc does not only offer writing man pages but various output formats. But at the moment, my focus are man pages for the terminal. > 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. Sorry, but I don't take the arguments of poorly structure or bad formatting as serious. As explained above, AsciiDoc offers everything DocBook does. My plan is not to offer the Guide as man pages. This is mainly new content describing the various options of the port commands. > 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. :) If I would have been unimpressed I might not have considered AsciiDoc which offers compatibility and interaction with DocBook. There are other ways to write man pages without writing plain roff, like latex2man, pod2man or any of the various markdown parsers. I am aware of the concerns you expressed, but maybe I just don't see that as the big issue as you do or I see ways to accomplish the goals. 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. Rainer _______________________________________________ macports-dev mailing list [email protected] http://lists.macosforge.org/mailman/listinfo.cgi/macports-dev
