[PATCH xserver 0/5] using util-macros to manage docs targets

[Gaetan Nadon]

On Sat, 2010-02-06 at 10:38 -0800, Jeremy Huddleston wrote:

> Series Reviewed-by: Jeremy Huddleston <jeremyhu at apple.com>
> 
> The only reservation I have is wrt the txt->text renaming.  The issue that I can see is when the generated file is present and the user tries to checkout a version with the file in git.  Is this renaming really the best way to handle this situation?  I'm sure this problem has come up before for other repositories.

The reason why the dmx.txt is both generated and in git is for
convenience. The original source is .sgml. If the linuxdoc tool is not
available, one can read the dmx.txt file. In a recent review this was
deemed to be important.

Currently, the code is extracted from git, and when built with linuxdoc,
a new dmx.txt is created and overwrites the one from git. Running 'make
clean' removes the dmx.txt and now git thinks the file is deleted. If
you try to pull and rebase, git refuses as your directory is not clean.
It also introduces duplication of files which will eventually be out of
sync.

Renaming dmx.txt to dmx.text avoid all these issues, except duplication.
As far as git is concerned, these are 2 different files.  The real
solution is to rework the doc generation with tools that are available
on all platforms and stop putting generated files in the tarball. Having
all the documentation properly built on a web site would alleviate the
need for such construct.

This issue is not really hurting anyone because the documents are not
generated by default. I wanted to fix these issues (knowing it is still
not the best way) so now we can turn on the generation by default, like
all the other xorg modules.

Thanks

> 
> On Feb 6, 2010, at 06:37, Gaetan Nadon wrote:
> 
> > Summary of visible external functional changes:
> > 
> > * --enable-builddocs replaced with generic util-macros --enable-devel-docs
> > * documentation now built by default
> > * dmx/doc git files dmx.txt and scaled.txt have renamed extension to .text
> > * message alerting builder when tarball cannot be created due to missing doxygen tool
> > 
> > See individual patches for details and rationales.
> > 
> > * all the rules under which a tarball may or may not be created have not changed.
> > * the content of the tarball has not changed. (save for .text extension)
> > * the documents retain their classifcation as "development" documents
> > 
> > Gaetan Nadon (5):
> >  config: use new XORG_ENABLE_DEVEL_DOCS util-macro
> >  doc: update .gitignore for dmx and xfree86 docs
> >  dmx/doc: resolve conflict between generated files also in git
> >  config: enable building documentation by default
> >  dmx/doc: alert builder when a tarball cannot be created
> > 
> > configure.ac                    |   14 +-
> > hw/dmx/Makefile.am              |    6 +-
> > hw/dmx/doc/.gitignore           |    8 +
> > hw/dmx/doc/Makefile.am          |   28 +-
> > hw/dmx/doc/dmx.text             | 2989 +++++++++++++++++++++++++++++++++++++++
> > hw/dmx/doc/dmx.txt              | 2989 ---------------------------------------
> > hw/dmx/doc/scaled.text          |  579 ++++++++
> > hw/dmx/doc/scaled.txt           |  579 --------
> > hw/xfree86/doc/Makefile.am      |    4 -
> > hw/xfree86/doc/sgml/.gitignore  |    5 +
> > hw/xfree86/doc/sgml/Makefile.am |    8 +-
> > 11 files changed, 3616 insertions(+), 3593 deletions(-)
> > create mode 100644 hw/dmx/doc/dmx.text
> > delete mode 100644 hw/dmx/doc/dmx.txt
> > create mode 100644 hw/dmx/doc/scaled.text
> > delete mode 100644 hw/dmx/doc/scaled.txt
> > create mode 100644 hw/xfree86/doc/sgml/.gitignore
> > 
> > _______________________________________________
> > xorg-devel mailing list
> > xorg-devel at lists.x.org
> > http://lists.x.org/mailman/listinfo/xorg-devel
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.x.org/archives/xorg-devel/attachments/20100206/a29c8ae8/attachment.htm 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : http://lists.x.org/archives/xorg-devel/attachments/20100206/a29c8ae8/attachment.pgp