kernel doc / docbook pdfdocs question

kernel doc / docbook pdfdocs question

[Doug Maxey]

Randy,

This may be slightly off topic for this list, but it does involve an
(as yet un-released) network driver. :)

Do you have any insight that could guide me toward a fix for an issue
seen with some header file constructs when trying to generate a pdf
docbook?

In my .tmpl file I do the "process my header file" construct:
...
!Ipath/to/myheader.h
...

In myheader.h an example decl that is giving me fits looks like:

struct foo {
	int bar;
	DECLARE_BITMAP(baz, LENGTH);
	int fotz;
};

It puts the bar and fotz decls in the output, but only outputs a
warning to stderr on the line with DECLARE_BITMAP, nothing about baz
(or DECLARE_BITMAP) is output into the .xml file.

My question is, would it be easier to pre-process the header, say with
gcc -EC via some rule in Documentation/DocBook/Makefile, or to try and
fix whatever gets called by scripts/basic/docbook?

I tried to find what the exact calling sequence was, but am getting
lost in what actually does the xml generation, and therefore how to
fix what is choking on the DECLARE_BITMAP.

Any tips will be very appreciated!

++doug

Re: kernel doc / docbook pdfdocs question

[Stephen Hemminger]

On Wed, 30 Sep 2009 14:59:36 -0500
Doug Maxey <dwm@enoyolf.org> wrote:

> 
> Randy,
> 
> This may be slightly off topic for this list, but it does involve an
> (as yet un-released) network driver. :)
> 
> Do you have any insight that could guide me toward a fix for an issue
> seen with some header file constructs when trying to generate a pdf
> docbook?
> 

Why clutter docbook output (which is supposed to be about general kernel
API's) with output for data structures in one driver.

Re: kernel doc / docbook pdfdocs question

[Doug Maxey]

On Wed, 30 Sep 2009 17:30:02 PDT, Stephen Hemminger wrote:
>On Wed, 30 Sep 2009 14:59:36 -0500
>Doug Maxey <dwm@enoyolf.org> wrote:
>
>> 
>> Randy,
>> 
>> This may be slightly off topic for this list, but it does involve an
>> (as yet un-released) network driver. :)
>> 
>> Do you have any insight that could guide me toward a fix for an issue
>> seen with some header file constructs when trying to generate a pdf
>> docbook?
>> 
>
>Why clutter docbook output (which is supposed to be about general kernel
>API's) with output for data structures in one driver.

It would be a general mechanism, and it would be to document an API.
There are other subsystems that use DECLARE_BITMAP() (e.g., scsi).
Just none at the moment that attempt to describe such a member,
possibly because there isn't a way to document it.  Dunno.  Build it
and they will come.  There is one party that is interested anyway.

Finally did find where this was getting warned about / tossed, in
kernel-doc itself. =)

++doug

Re: kernel doc / docbook pdfdocs question

[Randy Dunlap]

On Thu, 01 Oct 2009 00:42:27 -0500 Doug Maxey wrote:

> 
> On Wed, 30 Sep 2009 17:30:02 PDT, Stephen Hemminger wrote:
> >On Wed, 30 Sep 2009 14:59:36 -0500
> >Doug Maxey <dwm@enoyolf.org> wrote:
> >
> >> 
> >> Randy,
> >> 
> >> This may be slightly off topic for this list, but it does involve an
> >> (as yet un-released) network driver. :)
> >> 
> >> Do you have any insight that could guide me toward a fix for an issue
> >> seen with some header file constructs when trying to generate a pdf
> >> docbook?
> >> 
> >
> >Why clutter docbook output (which is supposed to be about general kernel
> >API's) with output for data structures in one driver.
> 
> It would be a general mechanism, and it would be to document an API.
> There are other subsystems that use DECLARE_BITMAP() (e.g., scsi).
> Just none at the moment that attempt to describe such a member,
> possibly because there isn't a way to document it.  Dunno.  Build it
> and they will come.  There is one party that is interested anyway.
> 
> Finally did find where this was getting warned about / tossed, in
> kernel-doc itself. =)

Hi,

Sorry for the delayed reply.  I was away yesterday.

What did you find in kernel-doc?  Something like the
"cannot understand prototype" message or something else?

Features/support in kernel-doc is mostly added on an as-needed basis.
Now that you have provided a sample, I can try to add support for it,
but it's not exactly a high priority for me... or you can add support
for it to kernel-doc and send a patch for it.  :)


---
~Randy