[PATCH xserver 0/5] using util-macros to manage docs targets
jeremyhu at freedesktop.org
Sat Feb 6 14:33:54 PST 2010
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
> 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.
>> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 3333 bytes
Desc: not available
Url : http://lists.x.org/archives/xorg-devel/attachments/20100206/2e7ce28b/attachment.bin
More information about the xorg-devel