I tagged 1.5.3-rc4 and it will soon be mirrored out.  This is

the last rc before the real thing, which I am hoping to happen

by mid August.  Until then, I won't look at anything but

regression fixes and documentation updates.  Please test this

one well.
  http://www.kernel.org/pub/software/scm/git/
  git-1.5.3-rc4.tar.{gz,bz2}			(tarball)

  git-htmldocs-1.5.3-rc4.tar.{gz,bz2}		(preformatted docs)

  git-manpages-1.5.3-rc4.tar.{gz,bz2}		(preformatted docs)

  testing/git-*-1.5.3-rc4-1.$arch.rpm		(RPM)
----------------------------------------------------------------
GIT v1.5.3 Release Notes (draft)

========================
Updates since v1.5.2

--------------------
* The commit walkers other than http are officially deprecated,

  but still supported for now.
* The submodule support has Porcelain layer.
* There are a handful pack-objects changes to help you cope better

  with repositories with pathologically large blobs in them.
* For people who need to import from Perforce, a front-end for

  fast-import is in contrib/fast-import/.
* Comes with git-gui 0.8.0.
* Comes with updated gitk.
* New commands and options.
  - "git log --date=<format>" can use more formats: iso8601, rfc2822.
  - The hunk header output from "git diff" family can be customized

    with the attributes mechanism.  See gitattributes(5) for details.
  - "git stash" allows you to quickly save away your work in

    progress and replay it later on an updated state.
  - "git rebase" learned an "interactive" mode that let you

    pick and reorder which commits to rebuild.
  - "git fsck" can save its findings in $GIT_DIR/lost-found, without a

    separate invocation of "git lost-found" command.  The blobs stored by

    lost-found are stored in plain format to allow you to grep in them.
  - $GIT_WORK_TREE environment variable can be used together with

    $GIT_DIR to work in a subdirectory of a working tree that is

    not located at "$GIT_DIR/..".
  - Giving "--file=<file&g...
[ message continues ]

Commit 281a53bb79786a6d7e54f9715cc8ad46fc2bdb0e introduced some stains on my man pages. They

look like:
           .ft C

                     A---B---C topic

                    /

               D---E---F---G master

           .ft
Versions (Mandriva 20071):
	asciidoc-8.1.0-1mdv2007.1

	docbook-style-xsl-1.72.0-1mdv2007.1
You should also mention that the man pages goes to a new location when installed.
-- robin
-

docbook xsl 1.72 is the culprit.  This version has extra escaping rules

that weren't in 1.71 and were removed for 1.73.  In addition these rules

are not backwardly compatible.  Basically, you can't build the git docs

properly with 1.72 ...
See http://thread.gmane.org/gmane.comp.version-control.git/52369
--

Julian
  ---

<seemant> you should always know where your inodes are, and who they are with

-

Can't build manpages, same error as

http://lists-archives.org/git/625107-having-problems-with-building-the-m... :
xmlto -m callouts.xsl man git-add.xml

runtime error: file

file:///usr/share/sgml/docbook/xsl-stylesheets-1.73.0/manpages/other.xsl line

129 element call-template

The called template 'read-character-map' was not found.
Regards,

ismail
--

Perfect is the enemy of good

-

Sigh...
The asciidoc toolchain used by us (either AsciiDoc 7 nor 8) does

not seem to work well with docbook-xsl 1.72 and 1.73, it seems.
If you can investigate where the breakage is to come up with

patches to make it format with newer docbook-xsl, without

breaking 1.71 (which k.org uses to make the preformatted

documentation in html and man branches), it would be very much

welcomed and appreciated.
I however have a slight suspition that the patch might end up to

be against either asciidoc or docbook-xsl package, not our

documentation...
-

How attached are we to asciidoc? Every time I do a clean build and sit

there twiddling my thumbs waiting for xmlto to do its thing, I think to

myself, "If this were a dedicated Perl script to do the syntax

transformations directly to man and html formats, it would blast through

all the .txt files in a second or two total." It seems outlandish to me

that it takes longer to build the (relatively small) documentation than

it does to build the actual code. Plus we constantly run into this sort

of problem.
Do we want to keep using asciidoc (e.g., so people can easily export to

other asciidoc-supported formats), or is a dedicated renderer something

we'd consider switching to? I have a flight from China back to the US

coming in a couple weeks; this could be a perfect little project to keep

me occupied between in-flight movies. It doesn't look like the syntax

transformations are very hard, and it'd be easy enough to verify

correctness by just comparing against the existing asciidoc output.
Am I correct in observing that "*roff -man" and HTML are the only two

output formats we care about, or do people use other formats in their

private branches?
-Steve
-

I cannot say that I am really happy with the current situation.

In my unscientific tests, it appears that we are spending about

50% of the time in asciidoc and 50% in xmlto for man backend

(total about 5 seconds for producing git.7 on my private box).

For xhtml11 backend, git.html takes about 2.3 seconds (for
I obviously do not speak for others, but the only format I care

about personally is the *.txt one.  We picked asciidoc primarily

because the source language was readable.
Unfortunately, AsciiDoc 8 requires authors to quote more

"special characters" we would rather be able to use as literals

(most importantly, plus sign '+') than AsciiDoc 7, and I am

afraid the trend to hijack more non alphabet letters as

"special" may continue.
If I read you correctly, what you are proposing to offer is a

clone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man

backends.  It is a subset in the sense that you will do only two

backends, but otherwise is a clone in the sense that you are

going to implement the input language we use (one thing I

personally care about while probably other people do not is the

conditional compilation "ifdef::stalenotes[]" in git.txt).
There is an obvious maintenance cost and risk with such a fork.
 * You would need to duplicate the AsciiDoc 7 manual and

   maintain it as well; otherwise, when later versions of

   AsciiDoc comes, people who update our documentation will

   refer to asciidoc website to learn the syntax, and find out

   that your dialect does not match what is described there.

   This already is the case, as our documentation source is

   written for AsciiDoc 7 and we use asciidoc7compatible support

   when running with AsciiDoc 8.
 * How much can we really rely on your fork to be kept

   maintained?  When we need newer mark-up that is not offered

   by AsciiDoc 7 clone, is it our plan to model that after

   AsciiDoc X (X > 7), or we just come up with an extension of

   our own?
 * What would happen when xhtml11 goes out of...
[ message continues ]

> your Perl magic.

I used asciidoc too but it was really PITA to install and use so I wrote

a small tool (ttman) in C which converts .txt files directly to man

pages. It doesn't have html support but you could use man2html for that.

Unfortunately it does not format as pretty html as asciidoc.
http://onion.dynserv.net/git/?p=cmus.git;a=tree;f=Doc;h=8ab4e92a6356d9cc...
It might be quite easy to extend ttman to output html too...
--

http://onion.dynserv.net/~timo/

-

Hi,
I disagree.  Whenever I had the need, installing asciidoc was pretty 
I was impressed!  Right until I saw that
	- it rolls its own parser/lexer without using bison/flex, which

	  makes it much longer than necessary,
	- it looks like a perl script doing the same job would have been

	  even smaller yet, and
	- the syntax is nowhere near asciidoc syntax.
The last point is really something to keep in mind.  We have not only a

large amount of documentation in that format, which would have to be

converted -- accurately! -- to the new format.  We also have quite a

number of documentation contributors which would have to be "migrated"

towards the new format.
I think that Steven's goal is a laudable one.  We have the 'man' and

'html' branch mainly for the reason that some cannot/wantnot install

asciidoc.
But I think that we do not have to have a _complete_ replacement.  I, for

one, would be happy to see a small script which converts all the man pages

more or less accurately, with the main goal to be _fast_ and having as

few dependencies as possible (I think Perl is okay here).
For official releases, I'd still want to rely on asciidoc.
Ciao,

Dscho
-

Well asciidoc doesn't even have a Makefile. You have to copy the files

manually (maybe it's easier now, I don't know). Also getting it work

correctly with xsl-stylesheets etc. was really frustrating experience.

Now there's asciidoc, xmlto etc. in Arch Linux community repo but I
I needed something really simple.  asciidoc's syntax is full of

surprises and it's much harder to parse.
Of course having a perl script which could convert asciidoc files

directly to man and html would be really nice.  We just need some brave
Agreed, rushing to change the documentation format wouldn't be wise.
--

http://onion.dynserv.net/~timo/

-

Naturally I am biased, but Texinfo might be an option.  The source is

editable without too much distraction, one can generate HTML, printed

output, cross-referenced info files (those are really convenient for

Emacs users), cross-referenced PDF output.  For man pages, one could

follow the path outlined in

<URL:http://gcc.gnu.org/onlinedocs/gccint/Man-Page-Generation.html>.

That is probably the weakest point.
Plain, user-readable ASCII text without any Texinfo markup can also be

generated.  One can even include images in info, PDF and HTML and have

those replaced by ASCII art in the plain text output.
There are some disadvantages: AFAIR, utf-8 characters will in general

not fly.  One needs to code accented characters more or less

explicitly.
Texinfo conversions are fast.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Yes and no. I am not offering to clone *all* of AsciiDoc, just whatever

subset is necessary to format the git documentation. (Of course, having

looked at this very little so far, perhaps that really is all of 
Actually, I disagree with this. If we were to fork our own document

formatter (or rather "implement" -- "fork" implies starting with the

existing code base) we would explicitly say its input was expected to be

in the "git documentation human-readable text format" rather than "git's

implementation of the AsciiDoc format." Then we could freely tweak

whatever parts of AsciiDoc we're not happy with, and precise 
My thought would be to come up with our own syntax; that's a logical

result of me not considering this anything but "a formatter whose input

looks suspiciously like AsciiDoc".
While I agree that that's extra work, it also seems to be the case that

(a) git hasn't actually needed new markup very often, and (b) we've

spent far more time dealing with AsciiDoc version-to-version

incompatibilities than it would likely take to implement whatever new 
If I do this I'll try to structure the code in such a way that new

formats could be added without huge pain. Will it be as flexible and

configurable as xmlto? Absolutely not, which is kind of the point of the

exercise. Adding a substantially different output format might require

logic changes to the formatter depending on the details, given that the

optimization here will be for speed rather than extreme flexibility.
On the other hand, I don't think that's a short-term enough concern to

be worth worrying too much about; it'll be a long, long time before

XHTML is completely replaced by anything else, just because of its

gargantuan installed base of existing documents. And it's not like we

can't decide to switch to another formatter down the road if we want to.

(Once we all have 64-core machines on our desktops, "make -j64" will 
Ah, that's a sticking point, and an answer to my "are there other output

...
[ message continues ]

Hi,
There have been a few suggestions to step away from asciidoc in this

thread now.  IMNSVHO the only switch which would actually make sense,

would be towards the Wiki format.
Why?
Because right now, we have a _ton_ of documentation on the Gitwiki, and

no easy way to import it back.  We also have at least one document which

is (semi-regularly) converted from ascii to Wiki markup.
Wiki markup is relatively easy to read (a bit more disruptive that

asciidoc), but granted, it is lacking features such as the conditional

thing Junio mentioned.
Ciao,

Dscho
-

Possibly I'm paranoid, but for the stuff we distribute in our source

tree I'd like to know who contributed, and to know that they were really

aware of the license.  That may be an obstacle to mass import of

documentation from the wiki--I don't know.
Whether the wiki markup is a sensible markup language is a separate

question.
--b.

-

Never looked at Ascii-doc... but how about finding the loopholes

in Ascii-doc to make it 10x faster?

That would benefit a larger user-base than just doing-it-ourself.
	Sam

-

Because AsciiDoc is only half of the toolchain we use. (Though in your

defense, I made the mistake of only mentioning AsciiDoc by name, rather

than "the AsciiDoc toolchain.") We run asciidoc's output through xmlto,

which is just as slow and is a highly general piece of software for

doing arbitrary transformations of XML documents. I won't say it's

impossible to speed up xmlto as well, of course, but it's probably an

order of magnitude more work than implementing a new parser/renderer for

our .txt files.
-Steve
-

Personally, I think it would make sense to move to a different

documentation system, or at least a different organization.  The

problem with the current layout is that it is basically flat.
A system such as info, in contrast, is hierarchical, and organized

with indexes and cross references making it much easier to find

things.  More importantly, it makes it possible to put things into

perspective: which commands are porcelain, which are plumbing?  What

do you do in a typical workflow?  What are the related internal data

structures?  Where are they documented?  Can I print or navigate a

complete PDF document explaining the whole system?
The manual pages of git have a high quality, but they remain manual

pages: they are all standalone, not putting the tool into a context or

hierarchy.  While the user manual is a place to start, it is more or

less added as an afterthought: it does not structure the available

documentation.
For Texinfo there is a large number of backends, and there are also

usable reader plugins (Tkinfo, and the presumably embeddable GNOME

"yelp" also displays info files and the embedded links, and of course

the wonderful Emacs info browser) for things like git-gui.
It may be that the asciidoc/Docbook workflow also contains ways to get

similarly useful stuff out: comments welcome.  I am just more

acquainted with Texinfo myself.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

You must be kidding. Texinfo is the worst documentation format EVER. And

the readers universally suck too, unless you're a total GNU emacs fan and

have been for a decade, and have problems understanding people who don't

like the all-in-one mentality.
There are absolutely _zero_ advantages in Texinfo over AsciiDoc. It has

all the same disadvantages, except the source files are *also* unreadable

(which is the one really nice feature of AsciiDoc - you can ignore

everything else, and just read the original .txt file).
			Linus

-

Oh come on.  It was the first hyperlinked and hierarchical format

before HTML even existed.  Its age shows, but the replacements have

not managed to produce anything more useful.  There have been

discussions about replacing the _info_ format with an HTML or XHTML

subset, however, that conveys the same amount of hierarchical
Actually, a decade ago the Emacs-internal info reader was worse than

it is now.
Any, after you have in your usual amicable manner declared anybody

insane that would not use the same tools as you, let us come back to
There are, of course, advantages to Texinfo.  Any system that is not

completely braindead has some unique advantages, and not everything

not designed by you is braindead.
One advantage to Texinfo is that it is _structured_: whether or not

you like the available info readers, there is the information "up",

"next", "previous" in every node, and every node has a hyperlinkable

name which you can use for referring to it.  And the info readers are

aware of that, and you can navigate using single keystrokes.
Now it may well be possible to put the same information into AsciiDoc

files, but there are no _readers_, bad or not, that would make use of

it.
I can specify something like
(info "(gcc) Extended Asm")
and when you are reading mail in Emacs, you can click on that line and

get to the respective page in a manual comprising hundreds of pages.

You can, of course, also type

info "(gcc) Extended Asm"

into your command line and use the standalone info reader to get

immediately to that line.
You can also get there by typing
info gcc

i assem <TAB>

and picking the right of three choices from the index.  The standalone

reader may not be pretty, but it does the job of accessing those

informations, and you can with single keypresses go up and forward in

a hierarchically organized, _structured_ manual of hundreds of pages.
And as opposed to AsciiDoc, there _are_ readers that make use of this
So what?
    makeinfo --plaintext
e...
[ message continues ]

Ugh. A documentation referencing system that works only in one

particular editor, or with one particular documentation format?
Please, the net decided on a standard for referencing resources long

ago, and they are called URLs.
-Peff

-

That works in readers of the info format.  Do HTML references work
The last time I looked, URLs were not a common way to implement

bookmarks except in HTML, namely "with one particular documentation

format".
And you don't need an HTML reader to use those "resources" in HTML?

Get real.
Anyway, the referencing in _Texinfo_ gets translated into info

references in info formats, URL bookmarks in HTML, PDF links in PDF

and a textual description (since you can't let a URL point into a

section of a plain text file) in plain text output.  All those are

_common_ ways of making references, and certainly "the net" has not

decided to pick any of those exclusively.
That the particular format "info" _also_ is able to represent the

respective information originally written into _Texinfo_ source is

hardly a disadvantage.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

I'm not talking about the _format_, I'm talking about the _referencing

system_. In other words, because URLs are a standard, there are

thousands of programs which recognize them and can find the resource

they mention (which in turn, may spawn an info reader, an html reader,

or some other interpreter).
What software is going to recognize (info "(gcc) Extended Asm") in your

email and realize that it's a reference to another document? None,

except emacs.
Though I don't especially like the info format or readers, my argument

here isn't against it. It is against the feature you mentioned being a

substantial benefit, since a large part of the world isn't reading their

email in emacs.
-Peff

-

Well, just for kicks I let firefox loose on
info:gcc#Extended Asm
It passed this off to the GNOME help browser, which displayed

"Loading...", used up 4 seconds of CPU time and 100M of memory, and

then hanged itself with a spinning cursor.
Interesting.  Starting the help browser manually and typing the URL

in, however, works.  It just seems to suicide when firefox tells it
So write it as a URL, if you want to.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

OK, I didn't know there was a URL style defined for info. Thanks for

pointing it out.
-Peff

-

Neither did I, actually.  If anybody would actually use them, I'd have

to teach firefox to pass them off to Emacs.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

The details can be found in <URL:man:uri(7)>.
If you find this syntax referring to a man page weird, you should

probably not complain about me writing (info "(gcc) Extended Asm") as

a reference.
When there are few readers of a format, it is easier to use a

"natural" spelling.
Anyway, I have seen in a posting about mathematics someone write an

equation including sqrt(3) and saw Emacs highlight this expression.

So I clicked on it.  And Emacs opened the man-page.  Definitely not

what I had expected...
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Wow. I've used the emacs one, and the stand-alone info one, and both are

pretty horrid. You're saying that they used to be _worse_?
(Admittedly, my GNU emacs-fu is very weak. I use an emacs-like editor, but

it's just an editor, and it's subtly different, so I actually find the 
None that any normal user would want to use. 
The thing is, html does a much better job of all of that, simply because

there are useful readers. The same, btw, goes for man-pages: even though

they have no structure at all, just the fact that normal people know how

to use them, they are actually superior to info pages!
That's something that the FSF seems to have missed in their push for info

format: a lot of FSF programs have really substandard man-pages, but that

doesn't mean that people read the info ones _anyway_. Because the readers

are so disgustingly horrible, plain man-pages are actually much more

useful, despite the fact that they don't have any cross-referencing etc.
		Linus

-

The problem is that html, not even now, offers useful standardized

structural navigation information, so no reader can offer keypresses

to follow the non-existing information.  I'd really like HTML to have

taken its place.  However, in spite of all the bloat of HTML

processors (firefox takes more memory than Emacs, and Emacs is my

bloody _desktop_), and in spite of it being orders of magnitude

slower, it does not offer this navigation.  It offers no cross-page

search facilities.
You can't navigate through the structure of the equivalent of hundreds

of printed pages in an HTML browser.  Not by navigating, not by plain

text searching.
I'll be all set to bury Texinfo once HTML has taken its place.
The standalone reader was rather horrid a few years ago: it used not

to know the normal page and cursor commands and beeped at quite a few
Linus, do you really think that the editor _you_ use is used by more

people than Emacs?  Think again.
Anyway, Emacs might, for all your polemics are worth, be an editor

that a "normal user" would not want to use: it has a tough learning

curve.  It has considerably flattened in recent years, and

particularly Emacs 22 is a big step forward, but no sane person would

use Emacs if there was anything else that sucked less.
There isn't.  And in spite of all your denial, there isn't for

Texinfo, either.  You can't do a plain text search through hundreds of

HTML pages.  You need a single page for that, and then navigation,

already bad in HTML, becomes absolutely horrid.
Your best bet nowadays might be a PDF reader with plain text search in

the document intended for printing.  Something which has a page layout

and fonts not suited for screen reading.
But there aren't.  Not for documents of several hundred pages.  Not

until you download all of them and then do a grep on the flat files

when you are looking for some keyword anywhere in the whole bunch.
That is an amount of suckage that neither Emacs nor the info reader
For single pages, yes.  F...
[ message continues ]

No.
But I'm also not confused enough to think that people should use

micro-emacs for reading man-pages.
The UNIX philosophy is "do one thing, and do it well". 
Man-pages with man. html with a web browser. And edit stuff with an

editor.
Why the *hell* do you confuse my choice of editor with my choice of

man-page format? I didn't. 
That whole "do everything in emacs" is a disease. And then emacs users

think that it's "sane".
		Linus

-

Could you refrain from using name-calling on everybody that does not

share your preferences?  It is annoying to hear you talk all the time
And Emacs does text, and does it well.  It is just that very much

information can ultimately be viewed as text.  For example, I can run

grep or locate inside of Emacs.  Nothing exciting.  And then I can

click on the lines those put out, and get moved to the corresponding

line in the source code, in my editor.  Again, nothing exciting, but

it does not work with disconnected tools without the glue Emacs

provides.  There are other IDEs providing that sort of thing, but

usually they work just with output they produced themselves.
Using Emacs to read man-pages means that I can grab manpage content

easily with my accustomed editing commands and paste them into a mail

I am composing.  Without having to use a mouse or GUI.
It enables workflows that are not possible outside of it.  It is ok if

you don't find the tradeoff appealing, but that does not make you

"normal" and other people "confused" and "insane".
So please get a grip and focus on what we were actually talking
Actually, Emacs "woman" does a pretty good job with those, offers

convenient man page name completion and works on Windows and similar
Why the hell do you keep changing the topic and go off on sideline
Focus.  How do you propose to manage documention of a hundred pages an

more conveniently, finding information easily by text, index,

hyperlinks?  A single large HTML page?  A documentation directory full

of *.txt files which you can grep through (not that Emacs would not be

useful for that, too)?
How do you find all information pertaining to "remote tracking

branches" in the git documentation?  Explain your workflow with that,

and explain why a sane person would prefer that over typing

info git

i remote TAB RET , , ,

and being taken to the respective text locations in turn.
Standalone info _is_ a single application doing a single job:

navigating large hyperlinked plain ...
[ message continues ]

You're the one who started talking about me expecting people to use *my*

editor. I had never done that. I had talked about the _reverse_: the

idiocy of emacs users expecting people to use that bloated piece of 
See? Can you not see that normal users don't want to have some random

emacs crap? In fact, even GNU emacs users (apart from the ones that have

used it for more than a decade) don't do it.
So stop this *insane* insistence of emacs. You should learn to just assume

that people don't even have it installed!
Anything that works with some random emacs mode is a total non-usable 
Oh, a single large html page is certainly better than emacs and info,

absolutely. Ask *any* normal person.
The fact that you cannot see that fact is a sign of your personal (and

rather odd) preferences.
			Linus

-

Yes, and it was not the topic.  So I pointed out your hypocrisy since

_you_ talk about editor preferences and "normal" people, while

preferring an editor yourself that is used by far fewer people.
You are still unable to focus on anything but name-calling and editors
Again, you are speaking for the rest of the world, conveniently

ignoring that more people use such a system than the one you use.  But
Which is why books nowadays always come as a single scroll without
Yes, name-calling and ad hominem attacks again.  It's getting old.  So

you think a single large html page containing everything in the

git/Documentation directory is the way we should organize git

documentation for the sake of the users?  All manual pages one after

the other, and some text in between explaining the connections?  In

one large file?
While harping on my sanity and normality because of contemplating

something more structured?
Please.
For what it's worth: Texinfo documents _can_ be converted into a

single HTML file as _well_ as a hierarchically split document with a

hyperlinked index.  So using Texinfo as a source format would _still_

allow preparing HTML in both multiple and single file form for the

sake of Torvalds-normal users.
Please try to remember that Texinfo is a _source_ format, and it

produces reasonably hyperrefed and coherent PDF and HTML documents as

well as plain ASCII.  That it is also able to produce working info

files should not bother you.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

I would welcome if the set of our documentation output formats

included *.info pages.
However, as the input format, texinfo _is_ painful.  AsciiDoc is

100x easier.  I've written documentaiton in texinfo format in

the past, and one thing I found quite painful was maintaining

the node header with prev/next links --- tedious, error prone

and boring.  There is no good editor to help you maintain them

other than Emacs texinfo mode as far as I know.
-

If you are able to figure out what to write.  Can you tell me how to

include one of the man pages in an appendix, with appropriate

substructure?  I can't.  It might be easy, but I find it impossible
    File: texinfo,  Node: makeinfo Pointer Creation,  Next: anchor,  Prev: node,  Up: Nodes
    6.4 Creating Pointers with `makeinfo'

    =====================================
    The `makeinfo' program has a feature for automatically determining node

    pointers for a hierarchically organized document.
      When you take advantage of this feature, you do not need to write the

    `Next', `Previous', and `Up' pointers after the name of a node.

    However, you must write a sectioning command, such as `@chapter' or

    `@section', on the line immediately following each truncated `@node'

    line (except that comment lines may intervene).
      In addition, you must follow the `Top' `@node' line with a line

    beginning with `@top' to mark the `Top' node in the file.  *Note

    `@top': makeinfo top.
      Finally, you must write the name of each node (except for the `Top'

    node) in a menu that is one or more hierarchical levels above the

    node's hierarchical level.
      This implicit node pointer insertion feature in `makeinfo' relieves

    you from the need to update menus and pointers manually or with Texinfo
Then don't maintain them.  It is not necessary.
Anyway, I suggest that people wanting to continue to berave me for

taking the word Texinfo into my mouth do this off-list.  It is very

much clear that Texinfo is no-go as a source documentation format for

Git: it makes a considerable ratio of developers foam at the mouth.

And that simply rules it out.
It also turns out that makeinfo2x-texi is able to produce rather good

Texinfo from stuff written for book output with Asciidoc.  Yes, there

are details missing, but it is nothing one could not slide in with

sed into the Texinfo file.  And adding the absent indexing information

can be done in Asciidoc: that ...
[ message continues ]

Actually, the prev/next/up parts of @node are optional in the input file

-- if you just leave them out, makeinfo will fill them in for you.
-miles
--

"Suppose we've chosen the wrong god. Every time we go to church we're

just making him madder and madder." -- Homer Simpson

-

No. Emacs _is_ odd. It's not even installed by default on most modern

Linux distributions.
There's no name-calling there. That's just a solid fact. You are

emacs-fixated when you keep on trying to bring up totally irrelevant 
You do not even know what you are talking about.
AsciiDoc is *also* a source format. But the source format is already

readable IN ITSELF. Which is the whole point!
I don't even bother to run "make doc".  I bet that is true of almost

everybody else too. Why? Because the *source* format we use (asciidoc) is

already basically as readable as any formatted man-page would ever be.
You don't have to even *know* that they are AsciiDoc pages - they're just

called "*.txt", and that's what they are. Text. With very minimal fixups

that *allow* them to be used as source for things like html, and

admittedly you get prettier output, but it really is perfectly

straightforward to just read them, in ways that pretty much no other

documentation format allows. Everybody else puts very intrusive crap in

there, so that you *have* to be aware of in ways you don't need to worry

about in AsciiDoc.
Headers? Lists? They look like headers and lists in the .txt files. No

need to think about it as a reader. 
See? Texinfo is decidedly inferior. But you don't have to take it so

personally. So is pretty much anything else. Anything XML/SGML is even

*worse*.
			Linus

-

Hi Linus,
Thus disparaging distributions that do install it.  I've not had

to pull any extra packages to get it so far, but I only update
Readable, just not writable.  It's markup language is a bunch

of special characters that require familiarity to understand.

Sure, you can peruse the text just fine, but why should this

sort of thing:
   = My Doc Title =
be preferred to:
    @settitle My Doc Title
@chapter, @section, @subsection really make a lot more sense to me

than this sort of cruft (my disparaging term):

Level 0 (top level):     ======================

Level 1:                 ----------------------

Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~

Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^

Level 4 (bottom level):  ++++++++++++++++++++++
It really boils down to preferences and familiarity and should
So do well-formatted .texi docs.  I don't really like anything

other than WYSIWYG, but that doesn't lend it self to reformatting
Bah!  They all have their drawbacks and preferences are going to weight

drawbacks differently.
So let's all dislike all our choices, eh?  Cheers - Bruce

-

Well, one problem I find that the documentation of both Asciidoc and

the connected Docbook toolchain is horribly subpar.
One part of the problem is that asciidoc.txt is written in Asciidoc,

and so you can't pick apart markup from content in the explanations

when reading the "readable in itself" documents.
Another problem is that most of the details of conversion to Docbook,

and what results in what XML output, are completely glossed over.  And

then there are further problems in that downstream Docbook processors

are documented even worse.
Then there is the problem that the markup can be redefined: the

sectioning underlines explained in the asciidoc documentation differ

from that _used_ in the documentation and again from that used in the

git documentation.
Now I can, in fact, use

docbook2x-texi --info --to-stdout user-manual.xml >user-manual.info

and get a working info file: not just basically working, but quite

fine (missing an index, though).
So there are "minor details" to fill in, like generated file names and

info directory entries.  Would you think that there is _any_ way of

finding out how to represent this in Docbook, or if you find out that,

how to get it from Asciidoc into Docbook?
Forget it.
Or things like including the manual pages in an appendix or elsewhere.

Any chance for that?  Slim, at least for me.
Texinfo source certainly looks less pretty than Asciidoc, but then

makeinfo can produce plain text output from it looking quite like

Asciidoc.  And whatever you may think about Texinfo as a format and

the generated info files and their readers: it is damn well

documented.
Asciidoc is quite readonly in many respects at the moment for me, and

I don't even know where to start in order to fix that.
And it does not help that there are multiple conversions involved with

a pretty opaque in-between XML representation.  In contrast, Texinfo

has a single well-documented source format and direct converters to

the target formats.
And its syntax is stra...
[ message continues ]

I'd like to do exactly that at some point.  I was hoping it would be as

simple as just adding a bunch of include:: statements, but there's

probably some more obstacles.  If someone had the time to look into what

would be required to get it working, I'd be grateful.
--b.

-

No, it's the same thing.
I started out by saying that Texinfo is horrible. It's horrible because it

doesn't *buy* you anything. The only thing it buys you (the "info" format)

is totally irrelevant, which I tried to explain.
AsciiDoc is much nicer. It does everything that Texinfo does for us, and

it's readable on its own as plain text, something Texinfo isn't.
So by advocating Texinfo, you're advocating something that is OBJECTIVELY

WORSE than what we have now.
And I tried to explain why, by pointing out that info files (which was the

case you tried to push as an advantage) aren't actually an advantage to

any normal user.
			Linus

-

By calling everybody names that would dare using it.  That's not
Readable plain text can be generated from Texinfo, so that is a red
Linus, your "normal user" does not get any documentation that can

usefully be employed for navigating a large body of documentation.
Anyway, this particular flame feast might be somewhat irrelevant: I

have read up a bit on AsciiDoc and Docbook, and it would appear that

quite a lot of what is needed for putting the required information for

indexes and nodes and other structural information is there in both

formats, and there is a tool called docbook2X that can presumably

convert to Texinfo (currently it barfs on the usermanual).  So

basically a lot can be achieved by structuring the existing

documentation into book form in AsciiDoc and peppering it with

indexing (apparently only a single index is possible) and other

structural information.
This will make the AsciiDoc sources less readable, while improving the

structural information content of the generated output, presumably

also when not going via Texinfo conversion.
Restructuring the available documentation into something that _can_ be

used as a coherent book, whether as a single PDF, single or multiple

HTML pages or even (avaunt!) info is probably not too horrible a

long-term prospect, and if info gives you the heebies, just don't call

"make info install-info", and you'll never get contaminated with it.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Ok, it turns out that
docbook2x-texi --info --to-stdout usermanual.xml >usermanual.info
cranks out (after a few inexplicable warnings/errors) a completely

functional info file.  The one thing that is conspicously missing is

indexing and info-dir information, and that's because it is not in the

source in the first place.
Whether you want to believe it or not, this already helps me

_considerably_ find my way around git.
So info, at least for the manual, can at the current point of time be

supported by merely adding Makefile targets.
Since an index is useful for other output formats, I don't think that

there should be objections to adding indexing info into the manual.

This takes the AsciiDoc form of ((primary)) for a primary entry

appearing in the text, and (((primary[, secondary[, third]]))) for a

hierarchical entry not appearing in the text itself.
Correct?
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Hi,
Hehe.  Statements like the first made me set up a certain procmail filter.

Made me much happier, too.
And now I see only one side of the conversation, which is actually pretty

funny... much like listening in into a heated phone conversation, and

guessing what the other one said. *grin*
Ciao,

Dscho
-

Interesting stance for somebody who has complained violently that I

should provide him with personal copies of mails to the list.  So you
You also get a chance of vetoing my patches only after they have been

applied, which happened a few times already.
To each his own, I guess.
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Actually html is able to represent that kind of information, though

browsers don't seem to take advantage of it.  E.g.  install something

like this firefox extension:
	http://www.christophm.de/software/firefox/cmSiteNavigation/
and then look at
	http://www.gnu.org/software/libc/manual/html_node/index.html
Doesn't seem to have keyboard shortcuts, but it's mildly useful.
--b.

-

Really? I find info a huge pain in the butt most of the time. I can't

just do a simple text search for the information I want in the relevant

manpage; I have to go navigating around to the appropriate subsection

(and that's assuming I know where it is) and am forced to use the

emacs-style pager whether I like it or not (not a big emacs fan here).

It always ticks me off when I go to read the manpage for some command

and it tells me to go read the info page if I want complete documentation.
I would definitely not want to move to a documentation system that

prevented me from typing "man git-commit" to get a list of all the

command line options for that command.
However, that said, I have no objection to an alternate view of the same

information that's organized differently.
Am I alone in my dislike of info, I wonder?
-Steve

-

I also find 'info' pages very painful to read. However, if you haven't

tried it, the "pinfo" viewer gives a much friendlier (IMHO) interface.

It's more or less based on the lynx interface.
  http://pinfo.alioth.debian.org/
-Peff

-

You are presumably talking about the standalone reader.  I never use

it, so can't really say much about it.  With Emacs, you just do C-s

and search.  Hitting C-s again will extend the search to the section,
Nobody said that we would want to get rid of man pages.
Anyway, with the info reader, you should at worst use something like

info git

i git-commit RET
I don't use the standalone info reader.  It is likely quite less

sophisticated and convenient than what Emacs does with info files.

The few times I have used it, I felt inconvenienced IIRC, though it

has supposedly been improved some time ago after being left in the

lurch for quite long.  But actually you can also use yelp to browse

info pages (point it at, say, info:coreutils).
So I would definitely agree with your assessment that _replacing_ the

man pages by info would not be the right way to go.  However, nobody

asked for that.  The idea was to use _Texinfo_, and this produces

plain text, HTML, info files, quite nice PDF and some other formats.

Of _course_, we want to have man pages as well.  I pointed out a

reference to the GCC project where they explain how they generate man

pages from Texinfo.  One would have to check whether this can be

applied to the git pages, of course.
There was also the question how to integrate documentation into

something like gitk, and there is a Tkinfo widget that could

conceivably be used.  Texinfo files can also be converted into flat

text files with basic markup (and man pages don't give you more than

that, anyway).
--

David Kastrup, Kriemhildstr. 15, 44793 Bochum

-

Hi,
There are so many reasons not to switch to info, but what you illustrated

is a very good one of those.
But yes, if you have the time, and it would be fun for you (before your

battery runs flat), I'd appreciate a small script to do a

quick-and-not-so-dirty conversion.  Heck, if you use some kind of object

orientation, I might be talked into providing the html backend.
Ciao,

Dscho
-

/me dons his asbestos skivvies.  
What about perldoc?  Thats about as minimal as it gets, yet can output

text or nroff quite nicely.  Don't pay much attention to html myself.
++doug
-

It's worth noting that we're a substantial portion of the asciidoc user

base, at least based on asciidoc's "Projects using AsciiDoc" page. We

could probably be influential in the asciidoc development if we tried

(maybe starting with a config file mechanism for controlling what

characters are markup instead of literal, so that we'll be able to make

documents which will work the same with all versions of asciidoc).
	-Daniel

*This .sig left intentionally blank*

-

Tempting, but...
 * The breakage that triggered this thread was not about asciidoc

   but about docbook-xsl.  AsciiDoc project cannot do much about

   it.
 * The slowness while formatting our manual pages are 50% from

   xmlto toolchain and even if AsciiDoc were were to be sped up

   20x, we will still spend 4-5 minutes to format ~140 manual

   pages.
-

For the latter, asciidoc ought to be able to generate manpages. Not sure

what to do about docbook (for the user manual); it seems generally prone

to compatibility problems. Perhaps we should go through latex instead,

since that's extremely stable these days, or go straight to html.
	-Daniel

*This .sig left intentionally blank*

-

Attached patch from Fedora against docbook-xsl 1.73 fixes the issue.
Regards,

ismail
=2D-=20

Perfect is the enemy of good

Thanks.  I'll mention this in the INSTALL document somewhere.
Perhaps the patch should go to docbook-xsl maintainers.
-

I sent a mail to docbook mailing list.
Regards,

ismail
--

Perfect is the enemy of good

-