Mailing-List: contact cygwin-help AT cygwin DOT com; run by ezmlm List-Subscribe: List-Archive: List-Post: List-Help: , Sender: cygwin-owner AT cygwin DOT com Mail-Followup-To: cygwin AT cygwin DOT com Delivered-To: mailing list cygwin AT cygwin DOT com To: cygwin AT cygwin DOT com X-Injected-Via-Gmane: http://gmane.org/ Path: not-for-mail From: Soren A Newsgroups: gmane.os.cygwin Subject: CSS in the User's Guide (was:Updating dll info...) Date: Thu, 22 Aug 2002 19:24:53 +0000 (UTC) Organization: Occasionally Sporadically Lines: 152 Message-ID: References: <20020821190517 DOT 11415 DOT qmail AT web20008 DOT mail DOT yahoo DOT com> NNTP-Posting-Host: ny-kenton2a-572.buf.adelphia.net X-Trace: main.gmane.org 1030044293 20814 24.51.94.60 (22 Aug 2002 19:24:53 GMT) X-Complaints-To: usenet AT main DOT gmane DOT org NNTP-Posting-Date: Thu, 22 Aug 2002 19:24:53 +0000 (UTC) User-Agent: Xnews/L5 X-Archive: encrypt Joshua Daniel Franklin wrote around 21 Aug 2002 news:20020821190517 DOT 11415 DOT qmail AT web20008 DOT mail DOT yahoo DOT com about %s: > References: > > <20020821154045 DOT GB21737 AT redhat DOT com> > > <20020821162436 DOT GE21737 AT redhat DOT com> > > > "Soren A" wrote: >> >> There are a couple standard mechanisms for including CSS stylesheets >> into the HTML document. None seem to be in use here. The >> documentation seems to be auto-generated by 'DocBook' which is >> something I know nothing about; I suspect that this is where some >> answers lie, though. > > DocBook FAQ: > > http://www.dpawson.co.uk/docbook/ > >> > I should make it clear that I know nothing about stylesheets. As >> > you noted, this is autogenerated code. If you see a specific >> > problem with it then a specific suggestion is appropriate. >> >> Yes. My specific suggestion is that you learn your tools. It is not >> farfetched to suppose that somewhere in the user documentation that >> exists for DocBook there is info pertaining to generation and >> configuration of stylesheets to complement the application's HTML >> output. > > I believe I'm actually the one who's supposed to be working on > improving the documentation. I have noticed that the HTML produced > could be better (especially that putting the ">" on the next line > issue), but I don't (yet?) know how to make it better. Well, that's the more important issue IMO. I am not sure, if you (or somebody else) is the person responsible for improving the documentation, why I should consider myself to be under an obligation to do research on your (or somebody else's) behalf -- that is research as in 'learning the specific user configuration options or mechanisms for the application being used to autogenerate the documentation'. Or looking for 'known bugs' documentation in such an application. OTOH, as I have already indicated both explicitly and implicitly all the way through (more on that just below*), it isn't very critical to address these issues because the Cygwin UG, while rather spartan, is basically usable. Very much more critical are the areas of the Guide which have fallen grievously out of date, exactly such as the DLL page had. IOW here, the content is a much more pressing issue than the presentation. > What I do know is that right now the HTML User's Guide looks decent in > most every browser, and I have heard about stylesheets that > Netscape 4.x does not support them very well. So I echo Chris': > >> > If you have a specific suggestion, I'd like to hear it. OK, it's my week for feeling generous: more specific suggestions. (1) Before making statements in support of a stance, especially a critical one, make sure you have at least half a clue about what you are talking about. Stylesheet support in Netscape 4x isn't the issue because the fundamental principle I referred to previously is that Stylesheets (CSS) 'fail gracefully' in all cases and don't prevent useability of the document they are being utilized in. Thus your hearsay, unresearched, less-half-understood factoid about CSS isn't relevent. (2) Actually look at the product being discussed for yourself. I've seen no evidence that either you or Chris have taken the time to view the source of one of the UG pages. What I have been talking about all along is that DocBook is *already using CSS* in the output that is the UG pages. The effort required to have discovered a fragment of a page chosen at random, like this one (using.html#USING-PATHNAMES): By default, the POSIX root / points to the system partition but it can be relocated to any directory in the Windows file system using the mount command. seems really minimal. I have no idea why the people I am responding to found it beyond them (`grep -i 'CLASS='' ???) . Only complete unfamiliarity with HTML -- and I grant that this is a possibility, I realize that not all C/C++ programmers are Web page builders -- would leave one unable to quickly recognize that in that fragment there are TWO references to Cascading Style Sheets: Yet these documents have no definition of what "COMMAND" or "FILENAME" should mean to the browser being asked to render the page. Half of the mechanism of CSS is *already* present in the documents, the other half is *missing*. Lastly, my final suggestion: (3) Don't emulate Chris Faylor in terms of taking verbal stances or attitudes. If you are looking for someone to emulate, I suggest a far more suitable role model would be a Linus Torvalds or a Larry Wall. As decribed by Eric Raymond with such admirable clarity in _The Cathedral and the Bazaar_, the leading figures of some of the largest, long-lived and successful Open Source software projects are persons noted for their humility and ability to invite the input of others in a way that attracts many supporters. When somebody else's idea was better than their own, they cheerfully adopted it and moved on, thus keeping the whole thing growing. Not only that, such figures seem to have the wisdom to understand that you don't *get* valuable input and contributions -- and go on getting them over time -- unless you maintain an open atmosphere in which people feel they are 'allowed' to enage in natural, relaxed exchanges. That means that you understand that a certain (large) amount of what gets posted isn't always going to be completely efficient and machine-like but will sometimes be sloppy and inefficient and seem wasteful of time. That part of it comes with the territory. And I don't think Larry Wall or Linus went on feeling like they had to reply to every single thread or topic that got introduced; they had the wisdom to understand when to stay behind the scenes and when to jump in. *(note above) Finally, I will point out -- and believe me when i observe that that i do not feel happy about the time i am taking away from my real projects in order to explain this obvious thing -- *when i post a BUG REPORT*, people will know it. I posted NOT a BUG REPORT but a simple query, seeking in an off-hand way to find out if anyone else might have noticed the anomalous inclusion of pointless CSS directives (the CLASS parameters in the tags cited above) in the UG pages. That's all. I did NOT even *invite* Chris Faylor to reply to my inquiry, much less *demand* it, and when he did so I answered him directly and in a detailed way even though I didn't particularly want to hear from him. I consider Cygwin to be far to important to myself and too many other people to be left in the sole care of a cygwin 'junta' led by Chris Faylor and disposed to snarling, confused recriminations on anybody they feel fails to make the proper obeisances. Furthermore, I think the requirements of a viable community of mutual support for Cygwin include the freedom to just post a "I-wonder-if" kind of message without it being torn apart by the habitual thugs surrounding the junta. I consider myself as having granted myself permission to post 'natural, normal, friendly' articles in discussion of things Cygwin on this List without needing pay any heed to the thugs. Fellow users who haven't been contaminated by this arrogant "Keeper of the Palace Keys" attitude of Chris' (which hurts him more than anyone else) are the people I am writing for and to. Regards, Soren A -- Unsubscribe info: http://cygwin.com/ml/#unsubscribe-simple Bug reporting: http://cygwin.com/bugs.html Documentation: http://cygwin.com/docs.html FAQ: http://cygwin.com/faq/