Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Anthony Liguori]

On 12/15/2011 07:43 AM, Avi Kivity wrote:
> On 12/15/2011 03:30 PM, Anthony Liguori wrote:
> > On 12/15/2011 03:37 AM, Avi Kivity wrote:
> > > On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> > > > By convention, documented headers now go in include/
> > >
> > > Dislike.
> >
> > I've been planning on doing this for a while.  I think it's a useful
> > way to help improve internal modularity.  It provides a consistent way
> > to indicate which headers represent "public" internal interfaces (like
> > the memory API) verses things that are really private headers specific
> > to a submodule (say block_int.h).
>
> If a submodule needs an internal header, it probably wants its own subdir.
>
> > We have a real problem internally with headers too.  It's almost
> > surprising how many lack guards, don't have proper #includes, etc.  By
> > moving all public headers to include/, it gives us a systematic way to
> > go through, clean up various headers, and have an idea of how much
> > work is left to be done.
>
> Still dislike.  But it's just dislike, not an opening shot into an
> extended discussion that will expand into coding style, proposals for
> changing the programming language, merging qemu into a subdirectory of
> another project, etc, as much fun as it promises to be.  Do it if you
> must, I'll live with it somehow.

Man, it's just not easy anymore to start epic flame wars...  I guess I'll have 
to go back to coding.

> > > Documentation should be built by default, so that errors in the format
> > > are detected (and break the build).
> >
> > I agree, but since we now are dealing with a fork of a common tool, I
> > didn't want to add a hard build dependency until I can get some
> > feedback on whether upstream is willing to consider our patch.
>
> Let's avoid a fork, either get it merged or find some other tool.

This is definitely the best tool for the job.  If we're not willing to live with 
underscores and upstream won't carry the patch, forking is our only option.  We 
can do it as a git submodule though which will make life fairly easy.

Regards,

Anthony Liguori

> > > Does this thing not support incremental builds?
> >
> > As best as I can tell, no.  Every other tool I've looked as suffers
> > from the same problem.
>
> Yeah, it's equivalent to a compiler doing most of its work during the
> link phase (=idea for patch).