Wireshark-dev: Re: [Wireshark-dev] [Wireshark-commits] rev 35213: /trunk/docbook/wsdg_src/ /tru
Date Index · Thread Index · Other Months · All Mailing Lists
Date Prev · Date Next · Thread Prev · Thread Next
From: Bill Meier <wmeier@xxxxxxxxxxx>
Date: Sat, 18 Dec 2010 12:41:47 -0500
On 12/18/2010 11:03 AM, Jeff Morriss wrote:

On 12/18/2010 06:13 AM, Joerg Mayer wrote:

On Fri, Dec 17, 2010 at 09:53:09PM -0500, Bill Meier wrote:

It seemed like a good idea to me.  I find trying to read
README.developer rather tedious, altho I do agree that a plain text file
can be grep'ed and etc.

If there's feeling that README.developer should be left as is, then I
can certainly revert the changes.


If someone is willing and able to create a readable ascii version from the
docbook (as proposed in another mail to this thread), then docbook
integration would be my preferred solution as it provides one source where
to search for programming information. Right now I use wsdg rarely because
of its format.


+1.

I never use the wsdg.  I used it once or twice for the
how-to-set-up-a-win32-build instructions and I looked at it a couple of
times after that when reviewing patches against it.

I use README.developer on a fairly regular basis.

:e doc/R<tab>dev<tab><enter>/whatever-I'm-looking-for

(optionally followed by a bunch of "n"s) gets me what I want pretty
quickly.  I can even then cut-n-paste a sample function call (for
example) into whatever file I'm editing, all without touching the mouse.

I wouldn't mind too much if the text-only version was generated, though
it might make it slightly less likely that I'd edit it.



OK: Obviously I jumped the gun on this.  :)
(In fact, if I really think about my own habits, I tend to use README.developer more than the WSDG). 

So:

1. For now, I'll revert the README.developer changes (and also
   the WSDG changes I made to include the style guide).

2. I'll look into "readable ascii version from the docbook".
   My first simple trials using lynx to do html to text for
   the StyleGuide section:
     The text appeared more or less OK but I wasn't really thrilled
     with the way the code fragments appeared.

3. In any case, I'm realizing that the deeper issue seems to be
   about good ways to document Wireshark for the developer.

   Obviously that can be an extensive discussion; It's certainly
   a good discussion to have, but it's"bigger than a breadbox".

   To be perfectly honest, in general my interests and focus
   are more on the Wireshark software itself.

Bill