Re: Updating dll info in the User's Guide

Re: Updating dll info in the User's Guide

[Joshua Daniel Franklin]

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. 

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.

__________________________________________________
Do You Yahoo!?
HotJobs - Search Thousands of New Jobs
http://www.hotjobs.com

--
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/

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

[Soren A]

Joshua Daniel Franklin <joshuadfranklin@yahoo.com> wrote around 21 Aug
2002 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/

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

[Jon Cast]

Soren A <soren_andersen@fastmail.fm> wrote in part:
> 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

I hope no-one thinks I'm speaking out of line when I say: if you don't
like how cgf is managing things, then fork.  Or at least start your
own mailing list.  But don't insist cgf (who is both maintainer of
Cygwin and manager of this list) change how he manages his stuff.
(software and mailing lists.)

>    Regards,
>     Soren A

Jon Cast

--
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/

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

[Soren A]

Jon Cast <jcast@ou.edu> wrote around 22 Aug 2002 
news:200208221938.g7MJch77007558@cate2-91.reshall.ou.edu:

> Soren A <soren_andersen@fastmail.fm> wrote in part:
>> 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
> 
> I hope no-one thinks I'm speaking out of line when I say: if you don't
> like how cgf is managing things, then fork.  Or at least start your
> own mailing list.  But don't insist cgf (who is both maintainer of
> Cygwin and manager of this list) change how he manages his stuff.
> (software and mailing lists.)
> 
>>    Regards,
>>     Soren A
> 
> Jon Cast

Ahh yes, a member of the 'thugs' speaks, as I've just referred to.
There's always been sycophants in every age of human history. 

My most recent follow-up to Joshua, that is selectively quoted above
with great care to *not* demonstrate wherein I started by demanding
anything at all, made special effort to note that no normal reading of
my postings in this discussion contain any wording by me that can be
construed as "demanding" anything, until I was accosted and accused of
"demanding" something. Of course what's "normal" for ordinary users
isn't obvious to juntas, thugs and sycophants. By definition.  

This particular guy should definitely be working for M$. He's got the
right mental outlook for closed, proprietary software and exactly the
wrong ethics for Open Source. 

  ** Thugs, junta principles and their sycophants are 
hereby *enthusiastically*  invited to killfile ALL my postings. **

Other persons are invited to reflect on the underrated axiom that "If
you are not part of the Solution, you are part of the Problem". Trying
to silence dissenters and discourage expression of dissenting viewpoints
is "being part of the problem." It's not "somebody elses' problem,
somewhere else (like Afghanistan?)", but mine and yours right here in
everyday life, in whatever sphere of society we operate. We ignore that
truth at our growing peril of waking up someday to discover that while
we were sleeping, it became "bad manners" and worse, to live according
to democratic principles (as opposed to waving flags and giving lip
service to 'patriotism'). 

  Best Regards,
   Soren A

-- 
  "It's about Power, and Abuse of Power."



--
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/

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

[Michael Schaap]

On 22-8-2002 21:24, Soren A wrote:
> 
> 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*. 

May I recommend that you read:
	http://www.w3.org/TR/html401/struct/global.html#h-7.5.2
*carefully*?
Please tell us where it insists that you must have CSS style rules 
whenever you use the 'class' attribute.

> 
> Lastly, my final suggestion:
>    (3) Don't emulate Chris Faylor in terms of taking verbal stances or 
> attitudes.

Now if this isn't the pot calling the kettle black ...

  - Michael


--
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/

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

[Christopher Faylor]

On Thu, Aug 22, 2002 at 07:24:53PM +0000, Soren A wrote:
>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*. 

Thanks for providing the specific information that I asked for.

I'll defer to Robert Collins on this one since he has infinitely
more knowledge about html and DocBook than I do.  I appreciate his
adding clarity here.

cgf

--
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/

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

[Christopher Faylor]

On Thu, Aug 22, 2002 at 11:30:06PM +0200, Michael Schaap wrote:
>>Lastly, my final suggestion:
>>(3) Don't emulate Chris Faylor in terms of taking verbal stances or
>>attitudes.
>
>Now if this isn't the pot calling the kettle black ...

You know, I can and do laugh at Soren and his email but being compared
to him seriously hurts.

cgf

--
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/

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

[Robert Collins]

[-- Attachment #1: Type: text/plain, Size: 791 bytes --]

On Fri, 2002-08-23 at 12:19, Christopher Faylor wrote:
> >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*. 

This is by design. Docbook automatically creates class attributes to
allow overriding the default display of the HTML via CSS *with no
further post processing*. The default then, is to have many undefined
classes - such as we do.

I'm not clear on what your original question was:
Was it 'there are unused class's in the User Guide HTML - does anyone
know why?' 
or 'there are unused class's in the User Guide HTML - someone should fix
this?'
or something else?

Cheers,
Rob

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Brian Gallew]

Soren A said:
[lots of condescending, sanctimonious crap clipped]
Did you read the replies?  Since you know all about HTML, I presume
you have heard of SGML?  Are you aware that, while it may *look* to
the average, assuming intellectual just like CSS, it is NOT, in fact,
CSS-related.

The Cygwin people seem to do a pretty good job by any standards except
yours.  Since you are neither paying them nor contributing anything
substantive either to them or to the community, please take this
opportunity to crawl back into the hole where you belong.

Thanks.



--
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/

Re: Updating dll info in the User's Guide

[Nicholas Wourms]

--- Robert Collins <rbcollins@cygwin.com> wrote:
> On Fri, 2002-08-23 at 12:34, Christopher Faylor wrote:
> 
> > Thanks for the clarification.  I'll be happy if I don't have to
> > understand the Docbook stuff.  As I've previously mentioned, I
> think it
> > may actually be a barrier to entry to working on the docs.  My
> Docbook
> > installation seems to break after each OS upgrade.  Maybe that
> explains
> > the strangely formatted html.
> 
> Likewise, as I've offered before, I'm happy to assist on docbook
> problems (related to Cygwin, naturally). Docbook is in *very* wide
> use,
> and there are plenty of resources for contributors to read to get
> up to
> speed. I don't think it's any more of a barrier to entry than
> understanding C or C++.

Well I think the lack of a decent docbook installation for cygwin is
a *big* barrier.  Docbook is such a PITA to setup that I detest every
second of it.  I mean we're talking about the type of setup
reminiscent of Redhat 3.0.3, where things got installed, but it was a
considierable timesink just to get the $%#^ing stuff to work right. 
Even then it seems to work by voodoo, and I always forget what I did
to make it work (lots of trial and error).  A small rant, but I
*really* *really* *really* wish the various docbook maintainers would
get on the same page and establish a freakin' standard as to how the
docbook directory structure should be layed out.  I fear the would-be
docbook maintainer, Jon, has become a victim of his skydiving hobby.
Either that, or he's just ignoring my e-mails =).  Oh well, hopefully
someone will step up to the plate.

Cheers,
Nicholas

__________________________________________________
Do You Yahoo!?
Yahoo! Finance - Get real-time stock quotes
http://finance.yahoo.com

--
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/

Re: Updating dll info in the User's Guide

[Robert Collins]

[-- Attachment #1: Type: text/plain, Size: 702 bytes --]

On Fri, 2002-08-23 at 12:34, Christopher Faylor wrote:

> Thanks for the clarification.  I'll be happy if I don't have to
> understand the Docbook stuff.  As I've previously mentioned, I think it
> may actually be a barrier to entry to working on the docs.  My Docbook
> installation seems to break after each OS upgrade.  Maybe that explains
> the strangely formatted html.

Likewise, as I've offered before, I'm happy to assist on docbook
problems (related to Cygwin, naturally). Docbook is in *very* wide use,
and there are plenty of resources for contributors to read to get up to
speed. I don't think it's any more of a barrier to entry than
understanding C or C++.

Cheers,
Rob


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Thu, Aug 22, 2002 at 09:01:37AM +1000, Robert Collins wrote:
>For the archive (as the FAQ reference may not be obvious to future
>searchers):
>
>Docbook generated HTML tags the HTML tags with similar classes to those
>used in the SGML source to allow _optional_ overriding of the format on
>a per-class basis. (For instance <H1 class="Title">. Here the class is
>title, and if wanted the title larger we could include an inline style
>sheet, or a reference to an includeable style sheet in a META tag in the
>HEAD). 
>
>Soren's reference to a 'missing' style sheet is because there is no
>style sheet specified, but we use all these styles.
>
>Soren: This is fine, it's by design.

Thanks for the clarification.  I'll be happy if I don't have to
understand the Docbook stuff.  HAs I've previously mentioned, I think it
may actually be a barrier to entry to working on the docs.  My Docbook
installation seems to break after each OS upgrade.  Maybe that explains
the strangely formatted html.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Robert Collins]

[-- Attachment #1: Type: text/plain, Size: 1589 bytes --]

On Thu, 2002-08-22 at 04:57, Christopher Faylor wrote:

> I suppose it is possible that you are referring to the use of the words
> "StyleSheet" in the meta tag at the top of the generated code.  AFAIK,
> meta tags do not have anything to do with style sheets, and the mention
> of a style sheet in this context is merely to illustrate that the
> DocBook HTML stylesheet was used to generate the html.  However, if you
> have more information on this, then it would certainly be welcome.
> Hmm.  Starting to repeat myself.
> 
> So, basically, in absence of any specifics, I'll just take your reported
> problems as indicating erroroneous assumptions on your part.  Feel free
> to taunt me about not knowing how to use my tools some more if it makes
> you feel better.  Either that or provide specific information.

Nyahh nyah nya-nyah nyah. Taunted yet?

Hope I'm not interfering my jumping in the middle of this mounting...
conversation.

For the archive (as the FAQ reference may not be obvious to future
searchers):

Docbook generated HTML tags the HTML tags with similar classes to those
used in the SGML source to allow _optional_ overriding of the format on
a per-class basis. (For instance <H1 class="Title">. Here the class is
title, and if wanted the title larger we could include an inline style
sheet, or a reference to an includeable style sheet in a META tag in the
HEAD). 

Soren's reference to a 'missing' style sheet is because there is no
style sheet specified, but we use all these styles.

Soren: This is fine, it's by design.

Rob


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 05:36:56PM +0000, Soren A wrote:
>Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002
>news:20020821162436.GE21737@redhat.com about %s: 
>
>> Not the same thing.  It's the standard bug reporting technique of
>> assuming that the people reading the mail are mind readers who are
>> clued into exact knowledge of a problem.
>
>Not really, Chris. In this case, the reality is not that there was
>anything inadaquate about my report/query, but rather the inadaquacy is
>entirely on your part. You are the documentation maintainer and yet you
>know nothing about aspects of the tools you use? HEY. 

Although I admitted to ignorance (I try to do that when I'm not up to
speed on something), you are assuming that I should apply expert status
to *you*.  You are assuming that I should take your notice of "something
wrong" as having some weight when there is, so far, no evidence that I
should do so.

Actually, ignorance is probably too strong a term for my state.  I
suppose I am now a "newbie" when it comes to style sheets.  I did scan
the appropriate documentation about style sheets and then inspected the
cygwin html.  I did that prior to sending my first message.  I don't see
anything wrong with the user guide html.  I'm willing to be proven
wrong, however, with specific examples, which you are, so far, unwilling
to provide.

I suppose it is possible that you are referring to the use of the words
"StyleSheet" in the meta tag at the top of the generated code.  AFAIK,
meta tags do not have anything to do with style sheets, and the mention
of a style sheet in this context is merely to illustrate that the
DocBook HTML stylesheet was used to generate the html.  However, if you
have more information on this, then it would certainly be welcome.
Hmm.  Starting to repeat myself.

So, basically, in absence of any specifics, I'll just take your reported
problems as indicating erroroneous assumptions on your part.  Feel free
to taunt me about not knowing how to use my tools some more if it makes
you feel better.  Either that or provide specific information.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Soren A]

Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002
news:20020821162436.GE21737@redhat.com about %s: 

> Not the same thing.  It's the standard bug reporting technique of
> assuming that the people reading the mail are mind readers who are
> clued into exact knowledge of a problem.

Not really, Chris. In this case, the reality is not that there was
anything inadaquate about my report/query, but rather the inadaquacy is
entirely on your part. You are the documentation maintainer and yet you
know nothing about aspects of the tools you use? HEY. 

> If you have a specific suggestion, I'd like to hear it.

It's really not a major issue. Users can write their own stylesheets,
and on a User Agent like Opera (and prob. Mozilla) they can configure
their UA to use them. The absence of the stylesheets (which REALLY
aren't that mysterious, Chris; they are by analogy just like a C header
but not a fatal error if they are missing...) doesn't impact the
documents in such a way as to render them unusable (which is precisely
the basic principle behind css to begin with). 

> 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. 

  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/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 12:56:36PM -0400, Christopher Faylor wrote:
>On Tue, Aug 20, 2002 at 09:28:22PM -0500, Joshua Daniel Franklin wrote:
>>Here is some new text to replace the section at
>>
>>http://cygwin.com/cygwin-ug-net/dll.html
>
>I've checked this new description into CVS and regenerated the web
>pages.  It's certainly better than what was there before even if it
>does conceivably need some tweaking.

Btw, some words indicating that it is possible to link directly against
the dll itself rather than generating a def file, would be nice in the
linking section.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Tue, Aug 20, 2002 at 09:28:22PM -0500, Joshua Daniel Franklin wrote:
>Here is some new text to replace the section at
>
>http://cygwin.com/cygwin-ug-net/dll.html

I've checked this new description into CVS and regenerated the web
pages.  It's certainly better than what was there before even if it
does conceivably need some tweaking.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 03:52:44PM +0000, Soren A wrote:
>gets to be told, as he has told so many others: "look at some code,
>what's wrong with you, don't you run a text editor?" ;-)

Not the same thing.  It's the standard bug reporting technique of
assuming that the people reading the mail are mind readers who are
clued into exact knowledge of a problem.

If you have a specific suggestion, I'd like to hear it.

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.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Soren A]

Christopher Faylor <cgf@redhat.com> wrote around 21 Aug 2002 
news:20020821154045.GB21737@redhat.com about %s:

> As is so often the case, the document maintainer would be fascinated
> by details.

And in this case, the document maintainer (which i presume you are
implying is you yourself?) gets to be told, as he has told so many
others: "look at some code, what's wrong with you, don't you run a text
editor?" ;-) 

There's really no more details to give than that stated in my previous
message. There's no external CSS stylesheet referenced on the Cygwin UG
pages. OK, want code? here's the header for one such page* as it is
presented to my User Agent: 

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
  <HTML
  ><HEAD
  ><TITLE
  >Expectations for UNIX Programmers</TITLE
  ><META
  NAME="GENERATOR"
  CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  "><LINK
  REL="HOME"
  TITLE="Cygwin User's Guide"
  HREF="cygwin-ug-net.html"><LINK
  REL="UP"
  TITLE="Cygwin Overview"
  HREF="overview.html"><LINK
  REL="PREVIOUS"
  TITLE="A brief history of the Cygwin project"
  HREF="brief-history.html"><LINK
  REL="NEXT"
  TITLE="Expectations for Windows Programmers"
  HREF="ov-ex-win.html"></HEAD
  >

* http://cygwin.com/cygwin-ug-net/ov-ex-unix.html

(Indentation done to emphasize that this is a pasted-in block of text. The 
malformed line breaks before the closing '>' of tags are NOT an artifact of 
my email agent or copy-and-paste procedure but are literally there in the 
Cygwin server docs as they are served to my User Agent.)

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.

   HTH,
    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/

Re: Updating dll info in the User's Guide

[Christopher Faylor]

On Wed, Aug 21, 2002 at 03:21:20PM +0000, Soren A wrote:
>Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
>news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:
>
>> Thanks for the update on dll-building. I almost missed this one...
>> I was thinking "Why doesn't someone just update the documentation?"
>
>BTW, in another vein, but also regarding the Cygwin UG there's a small
>detail: there seems to be a stylesheet gone missing from the pages. The
>markup on the pages reference CSS classes that aren't defined and
>clearly are supposed to come from an external stylesheet that's declared
>somewhere in each HTML page's headers? Does the document maintainer know
>about this? 

As is so often the case, the document maintainer would be fascinated by
details.

cgf

--
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/

Re: Updating dll info in the User's Guide

[Gerrit P. Haase]

Hallo Joshua,

Am Mittwoch, 21. August 2002 um 04:28 schriebst du:

> Gerrit and other dll-builders,

> Thanks for the update on dll-building. I almost missed this one...
> I was thinking "Why doesn't someone just update the documentation?"
> then realized "Hey, I volunteered to do that, didn't I?"
> (BTW, everyone--could I get heads-up about the User's Guide like David gets
> about the FAQ?)

> Here is some new text to replace the section at

> http://cygwin.com/cygwin-ug-net/dll.html

> that begins with "Unfortunately, the process for building a dll is, well,
> convoluted. You have to run five commands, like this"
> This is not the actual patch, I will submit one of those after
> I verify that I've got the subject matter correct.
> Please read carefully since I'm not an expert in this area and may have
> mixed up some terminology or concepts.

> --------Begin new text--------

Maybe it would be easier to get into with a real example
(s.th. like this, without your comments):

dlltest.C:
==========
#include<iostream>
int
hello ()
{
  using namespace std;
  cout << "Just another dll hacker,";
}

$ g++ -c dlltest.C

$ g++ -shared -o mydll.dll \
> -Wl,--out-implib=libmydll.dll.a \
> -Wl,--export-all-symbols \
> -Wl,--enable-auto-import \
> -Wl,--whole-archive dlltest.o \
> -Wl,--no-whole-archive


exetest.C:
==========
void hello ();

int
main ()
{
  hello ();
  return 1;
}

$ g++ -o exetest exetest.C -L/d/dlltest -lmydll

$ ./exetest
Just another dll hacker,


> Fortunately, with the latest gcc and binutils the process for building a dll
> is now much simpler. Say you want to build this minimal function in mydll.c:

> #include <windows.h>

> int WINAPI
> mydll_init(HANDLE h, DWORD reason, void *foo)
> {
>   return 1;
> }

> First compile mydll.c to object code:

> gcc -c mydll.c

> Then, tell gcc that it is building a shared library:

> gcc -shared -o mydll.dll mydll.o

> That's it! However, if you are building a dll as an export library,
> you will probably want to use the complete syntax:

> gcc -shared -o cyg${module}.dll \
>     -Wl,--out-implib=lib${module}.dll.a \
>     -Wl,--export-all-symbols \
>     -Wl,--enable-auto-import \
>     -Wl,--whole-archive ${old_lib} \
>     -Wl,--no-whole-archive ${dependency_libs}

> Where ${module} is the name of your DLL, ${old_lib} are all
> your object files, bundled together in static libs or single object
> files and the ${dependency_libs} are import libs you need to
> link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'

> --------End new text--------



-- 
=^..^=


--
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/

Re: Updating dll info in the User's Guide

[Soren A]

Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:

> Thanks for the update on dll-building. I almost missed this one...
> I was thinking "Why doesn't someone just update the documentation?"

BTW, in another vein, but also regarding the Cygwin UG there's a small
detail: there seems to be a stylesheet gone missing from the pages. The
markup on the pages reference CSS classes that aren't defined and
clearly are supposed to come from an external stylesheet that's declared
somewhere in each HTML page's headers? Does the document maintainer know
about this? 

TIA,
  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/

Re: Updating dll info in the User's Guide

[Soren A]

Joshua Daniel Franklin <joshua@iocc.com> wrote around 20 Aug 2002 
news:Pine.CYG.4.44.0208202127280.1336-100000@joshua.iocc.com about %s:

> Here is some new text to replace the section at
> 
> http://cygwin.com/cygwin-ug-net/dll.html
> 
> that begins with "Unfortunately, the process for building a dll is, well,
> convoluted. You have to run five commands, like this"

I am making my own local copy of the document right now. Could you confirm 
for me at what point your replacement section _ends_, please? Is it at the 
next major section heading, "Linking Against DLLs"? I am not confidently 
familiar enough with the material to know that the whole section between 
the two points can be jettisoned.

  Thanks!!!
    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/

Updating dll info in the User's Guide

[Joshua Daniel Franklin]

Gerrit and other dll-builders,

Thanks for the update on dll-building. I almost missed this one...
I was thinking "Why doesn't someone just update the documentation?"
then realized "Hey, I volunteered to do that, didn't I?"
(BTW, everyone--could I get heads-up about the User's Guide like David gets
about the FAQ?)

Here is some new text to replace the section at

http://cygwin.com/cygwin-ug-net/dll.html

that begins with "Unfortunately, the process for building a dll is, well,
convoluted. You have to run five commands, like this"
This is not the actual patch, I will submit one of those after
I verify that I've got the subject matter correct.
Please read carefully since I'm not an expert in this area and may have
mixed up some terminology or concepts.

--------Begin new text--------
Fortunately, with the latest gcc and binutils the process for building a dll
is now much simpler. Say you want to build this minimal function in mydll.c:

#include <windows.h>

int WINAPI
mydll_init(HANDLE h, DWORD reason, void *foo)
{
  return 1;
}

First compile mydll.c to object code:

gcc -c mydll.c

Then, tell gcc that it is building a shared library:

gcc -shared -o mydll.dll mydll.o

That's it! However, if you are building a dll as an export library,
you will probably want to use the complete syntax:

gcc -shared -o cyg${module}.dll \
    -Wl,--out-implib=lib${module}.dll.a \
    -Wl,--export-all-symbols \
    -Wl,--enable-auto-import \
    -Wl,--whole-archive ${old_lib} \
    -Wl,--no-whole-archive ${dependency_libs}

Where ${module} is the name of your DLL, ${old_lib} are all
your object files, bundled together in static libs or single object
files and the ${dependency_libs} are import libs you need to
link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'

--------End new text--------


--
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/