CSS in the User's Guide (was:Updating dll info...)

[Soren A <soren_andersen at fastmail dot fm>]

Joshua Daniel Franklin <joshuadfranklin@yahoo.com> wrote around 21 Aug
2002 20020821190517.11415.qmail@web20008.mail.yahoo.com">news:20020821190517.11415.qmail@web20008.mail.yahoo.com about %s: 

> References: <Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com>
> <Xns927173B917AEDsoren1Gmane@80.91.224.249>
> <20020821154045.GB21737@redhat.com> 
> <Xns9271790BEA4BDsoren1Gmane@80.91.224.249>
> <20020821162436.GE21737@redhat.com> 
> <Xns92718AB657BD2soren1Gmane@80.91.224.249> 
> 
> "Soren A" <soren_andersen@fastmail.fm> 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 <TT CLASS="FILENAME">/</TT> points to
  the system partition but it can be relocated to any directory in
  the Windows file system using the <B CLASS="COMMAND">mount</B>
  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: 

  <TT CLASS="FILENAME">
  <B CLASS="COMMAND">

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/