Shipping man pages?

Shipping man pages?

[Tilman Sauerbeck]

[-- Attachment #1: Type: text/plain, Size: 534 bytes --]

Hi,
atm, the git release tarballs don't contain man pages. They can be
generated from the asciidoc source files, which makes the build depend
on python and asciidoc.

That's *very* inconvenient; would it be possible to include the man
pages in the release tarball?

Or maybe offer them in a separate tarball?

Thanks,
Tilman

-- 
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Shipping man pages?

[Junio C Hamano]

Tilman Sauerbeck <tilman@code-monkey.de> writes:

> atm, the git release tarballs don't contain man pages.

I ship *source* tarball.

I also happen to do RPM for people who do not want to build from
the source (btw, I do that from pure inertia). In addition,
preformatted manual pages and html docs are available from man
and html branches of the git.git repository.

If you are building from the source, please build from the
source.  Everything you need is right there.

If you don't build from the source, please use whatever binary
distribution available out there.  RPM happens to be available
from kernel.org.  If you are on Debian/Ubuntu/Gentoo/others,
please ask your distribution packager to include the manpages
and html docs, if they don't already.

Why does this have to come up so often, and everybody who asks
for them never supplies the patch to do so?

> Or maybe offer them in a separate tarball?

Things that are buildable from the source do not belong in the
source tarball.  If somebody wants to do this as a patch, I can
be talked into accepting it, but the build procedure should
build a separate tarball (or two; one for man and another for
woman^Whtml).

Re: Shipping man pages?

[Mark Rosenstand]

On Thu, 2006-05-18 at 01:06 -0700, Junio C Hamano wrote:
> Tilman Sauerbeck <tilman@code-monkey.de> writes:
> 
> > atm, the git release tarballs don't contain man pages.
> 
> I ship *source* tarball.

Which is great for generating binaries and other things that are likely
to be incompatible across systems.

> I also happen to do RPM for people who do not want to build from
> the source (btw, I do that from pure inertia). In addition,
> preformatted manual pages and html docs are available from man
> and html branches of the git.git repository.
> 
> If you are building from the source, please build from the
> source.  Everything you need is right there.

But asciidoc is a royal PITA to package or install - it doesn't even
provide a Makefile: http://www.methods.co.nz/asciidoc/userguide.html#X38

Additionally it carries the whole docbook dependency chain with it.

> If you don't build from the source, please use whatever binary
> distribution available out there.  RPM happens to be available
> from kernel.org.  If you are on Debian/Ubuntu/Gentoo/others,
> please ask your distribution packager to include the manpages
> and html docs, if they don't already.

Even the packagers are likely to hate the unneccessary asciidoc
dependency. As a result some of the small distributions that don't have
the manpower to support 1000+ packages choose to ship git without the
man pages, which is a shame, IMO.

> Why does this have to come up so often, and everybody who asks
> for them never supplies the patch to do so?

Because it seems like a political decision rather than a technical one
(it's trivial to add the docs as a prerequisite for the dist target.)

> > Or maybe offer them in a separate tarball?
> 
> Things that are buildable from the source do not belong in the
> source tarball.  If somebody wants to do this as a patch, I can
> be talked into accepting it, but the build procedure should
> build a separate tarball (or two; one for man and another for
> woman^Whtml).

That would be great! I'd love to submit a patch, but I wouldn't be able
to test it, because I'd need asciidoc.

Re: Shipping man pages?

[Junio C Hamano]

Mark Rosenstand <mark@borkware.net> writes:

> On Thu, 2006-05-18 at 01:06 -0700, Junio C Hamano wrote:
>
>> If you are building from the source, please build from the
>> source.  Everything you need is right there.
>
> But asciidoc is a royal PITA to package or install - it doesn't even
> provide a Makefile: http://www.methods.co.nz/asciidoc/userguide.html#X38
>
> Additionally it carries the whole docbook dependency chain with it.

That's a consequence of _your_ choice to build the documentation
files from the source, when I give you preformatted files in
html/man branches and/or prepackaged binary distributions.  Even
plain "make all" nor "make install" do not build them.

IOW, not my problem.

We accomplish things by saying "I did this, it solves my
problem, and it would help others -- so I share", not by
demanding others to do things for you by saying "If you do this,
it would solve my problem.  Now go do it".  That's how open
source works.

>> Why does this have to come up so often, and everybody who asks
>> for them never supplies the patch to do so?
>
> Because it seems like a political decision rather than a technical one

I do not see why that is political.  Do you need a politician to
tell you what is source and what isn't?

> (it's trivial to add the docs as a prerequisite for the dist target.)

Being trivial does not change things a whit, because I do not do
things I consider useless only because they are trivial.

You have to first convince me that it is useful to others, and
one way to do so is by showing that you care deeply enough about
it -- doing the work yourself (instead of demanding _me_ to do
something I do not believe is a good idea yet) is a good way to
do so.  That would tell me that it is a real problem to you.
When that happens, I might start considering the possibility
that a solution to that problem may be useful to other people.

And it actually makes things actively worse to whine without
doing the work yourself when the necessary change is trivial.
You are saying that you cannot be bothered to do that yourself
even though the change is trivial, which implies you _can_ live
without formatted pages just fine.  The conclusion is that not
having the formatted pages is not such a big deal to you (after
all, asciidoc toolchain might be a bear to install, but the
documents formatted in it are very easy to read in the source
form).

Now, with a patch, Tilman showed us he cares deeply enough, so
I'll take a look at it.  Thanks, Tilman.

Re: Shipping man pages?

[Linus Torvalds]

On Thu, 18 May 2006, Junio C Hamano wrote:
> 
> That's a consequence of _your_ choice to build the documentation
> files from the source, when I give you preformatted files in
> html/man branches and/or prepackaged binary distributions.  Even
> plain "make all" nor "make install" do not build them.

Btw, in case others didn't notice, the easiest way to install the 
pre-packaged branch is a truly disgusting hack:

	cd git
	git tar-tree man | (cd /usr/share/man ; tar xvf -)

or similar (yeah, you need to be root to do the unpack, of course, and 
you may need to change the /usr/share/man to whatever is appropriate for 
your distribution).

No need to actually even check out the 'man' branch.

		Linus

Re: Shipping man pages?

[Tilman Sauerbeck]

[-- Attachment #1.1: Type: text/plain, Size: 1049 bytes --]

Junio C Hamano [2006-05-18 01:06]:
> Tilman Sauerbeck <tilman@code-monkey.de> writes:
> 
> [snip]
> 
> Why does this have to come up so often, and everybody who asks
> for them never supplies the patch to do so?

If it comes up that often it would indicate that this is actually a
concern to many people o_O

Also, I prefer to ask whether a patch would even be accepted so I don't
waste 3 hours of my life trying to figure out how to set up asciidoc and
docbook.

> > Or maybe offer them in a separate tarball?
> 
> Things that are buildable from the source do not belong in the
> source tarball.  If somebody wants to do this as a patch, I can
> be talked into accepting it, but the build procedure should
> build a separate tarball (or two; one for man and another for
> woman^Whtml).

I attached a patch.

Regards,
Tilman

-- 
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

[-- Attachment #1.2: git-doc-dist.patch --]
[-- Type: text/plain, Size: 1555 bytes --]

Created a dist target for Documentation/Makefile that tars up the man pages and html files.

Signed-off-by: Tilman Sauerbeck <tilman@code-monkey.de>


---

 Documentation/Makefile |   16 +++++++++++++++-
 1 files changed, 15 insertions(+), 1 deletions(-)

f8b6b70c89364418724899ab5ca28aaaf3eee7dc
diff --git a/Documentation/Makefile b/Documentation/Makefile
index c1af22c..271d9e4 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -31,6 +31,7 @@ man7=$(mandir)/man7
 # DESTDIR=
 
 INSTALL?=install
+TAR?=tar
 
 #
 # Please note that there is a minor bug in asciidoc.
@@ -55,6 +56,18 @@ install: man
 	$(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1)
 	$(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7)
 
+-include ../GIT-VERSION-FILE
+
+dist: html man
+	@mkdir -p git-doc-{html,man}-$(GIT_VERSION)
+	@cp $(DOC_HTML) git-doc-html-$(GIT_VERSION)
+	@cp $(DOC_MAN1) $(DOC_MAN7) git-doc-man-$(GIT_VERSION)
+	
+	@for d in html man; do \
+		$(TAR) cf git-doc-$$d-$(GIT_VERSION).tar git-doc-$$d-$(GIT_VERSION) && \
+		rm -rf git-doc-$$d-$(GIT_VERSION) && \
+		gzip -f -9 git-doc-$$d-$(GIT_VERSION).tar \
+	; done
 
 #
 # Determine "include::" file references in asciidoc files.
@@ -73,7 +86,8 @@ README: ../README
 
 
 clean:
-	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README
+	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README \
+	      git-doc-{html,man}-$(GIT_VERSION).tar.gz
 
 %.html : %.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
-- 
1.3.3


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Shipping man pages?

[Fernando J. Pereda]

[-- Attachment #1: Type: text/plain, Size: 823 bytes --]

On Thu, May 18, 2006 at 09:46:32AM +0200, Tilman Sauerbeck wrote:
> Hi,
> atm, the git release tarballs don't contain man pages. They can be
> generated from the asciidoc source files, which makes the build depend
> on python and asciidoc.
> 
> That's *very* inconvenient; would it be possible to include the man
> pages in the release tarball?
> 
> Or maybe offer them in a separate tarball?

Hi Tilman,

Actually Junio has 'html' and 'man' branches in his git.git repository
so you just have to use git tar-tree on them.

I do this for the Gentoo packages, you can grab a tarball from any of
our mirrors, the files are called git-{html,man}-VERSION.tar.bz2

- ferdy

-- 
Fernando J. Pereda Garcimartín
Gentoo Developer (Alpha,net-mail,mutt,git)
20BB BDC3 761A 4781 E6ED  ED0B 0A48 5B0C 60BD 28D4

[-- Attachment #2: Type: application/pgp-signature, Size: 191 bytes --]