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

[Jeremy Huddleston]

Ok, fair enough.  It's not ideal, but as long as you're working towards the ideal, I'm happy =)


On Feb 6, 2010, at 14:01, Gaetan Nadon wrote:

> 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 --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3333 bytes
Desc: not available
Url : http://lists.x.org/archives/xorg-devel/attachments/20100206/2e7ce28b/attachment.bin