[ANNOUNCE] GIT 1.5.3-rc4

[ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

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>" option to "git config" is the same as
    running the command with GIT_CONFIG=<file> environment.

  - "git log" learned a new option "--follow", to follow
    renaming history of a single file.

  - "git-filter-branch" lets you rewrite the revision history of
    specified branches. You can specify a number of filters to
    modify the commits, files and trees.

  - "git-cvsserver" learned new options (--base-path, --export-all,
    --strict-paths) inspired by git-daemon.

  - "git daemon --base-path-relaxed" can help migrating a repository URL
    that did not use to use --base-path to use --base-path.

  - "git-commit" can use "-t templatefile" option and commit.template
    configuration variable to prime the commit message given to you in the
    editor.

  - "git-submodule" command helps you manage the projects from
    the superproject that contain them.

  - In addition to core.compression configuration option,
    core.loosecompression and pack.compression options can
    independently tweak zlib compression levels used for loose
    and packed objects.

  - "git-ls-tree -l" shows size of blobs pointed at by the
    tree entries, similar to "/bin/ls -l".

  - "git-rev-list" learned --regexp-ignore-case and
    --extended-regexp options to tweak its matching logic used
    for --grep fitering.

  - "git-describe --contains" is a handier way to call more
    obscure command "git-name-rev --tags".

  - "git gc --aggressive" tells the command to spend more cycles
    to optimize the repository harder.

  - "git repack" learned a "window-memory" limit which
    dynamically reduces the window size to stay within the
    specified memory usage.

  - "git repack" can be told to split resulting packs to avoid
    exceeding limit specified with "--max-pack-size".

  - "git fsck" gained --verbose option.  This is really really
    verbose but it might help you identify exact commit that is
    corrupt in your repository.

  - "git format-patch" learned --numbered-files option.  This
    may be useful for MH users.

  - "git format-patch" learned format.subjectprefix configuration
    variable, which serves the same purpose as "--subject-prefix"
    option.

  - "git tag -n -l" shows tag annotations while listing tags.

  - "git cvsimport" can optionally use the separate-remote layout.

  - "git blame" can be told to see through commits that change
    whitespaces and indentation levels with "-w" option.

  - "git send-email" can be told not to thread the messages when
    sending out more than one patches.

  - "git config" learned NUL terminated output format via -z to
    help scripts.

  - "git init -q" makes the command quieter.

* Updated behavior of existing commands.

  - "gitweb" can offer multiple snapshot formats.

    ***NOTE*** Unfortunately, this changes the format of the
    $feature{snapshot}{default} entry in the per-site
    configuration file 'gitweb_config.perl'.  It used to be a
    three-element tuple that describe a single format; with the
    new configuration item format, you only have to say the name
    of the format ('tgz', 'tbz2' or 'zip').  Please update the
    your configuration file accordingly.

  - "git diff" (but not the plumbing level "git diff-tree") now
    recursively descends into trees by default.

  - The editor to use with many interactive commands can be
    overridden with GIT_EDITOR environment variable, or if it
    does not exist, with core.editor configuration variable.  As
    before, if you have neither, environment variables VISUAL
    and EDITOR are consulted in this order, and then finally we
    fall back on "vi".

  - "git rm --cached" does not complain when removing a newly
    added file from the index anymore.

  - Options to "git log" to affect how --grep/--author options look for
    given strings now have shorter abbreviations.  -i is for ignore case,
    and -E is for extended regexp.

  - "git svn dcommit" retains local merge information.

  - "git config" to set values also honors type flags like --bool
    and --int.

  - core.quotepath configuration can be used to make textual git
    output to emit most of the characters in the path literally.

  - "git mergetool" chooses its backend more wisely, taking
    notice of its environment such as use of X, Gnome/KDE, etc.

  - "gitweb" shows merge commits a lot nicer than before.  The
    default view uses more compact --cc format, while the UI
    allows to choose normal diff with any parent.

  - snapshot files "gitweb" creates from a repository at
    $path/$project/.git are more useful.  We use $project part
    in the filename, which we used to discard.

  - "git cvsimport" creates lightweight tags; there is no
    interesting information we can record in an annotated tag,
    and the handcrafted ones the old code created was not
    properly formed anyway.

  - "git-push" pretends that you immediately fetched back from
    the remote by updating corresponding remote tracking
    branches if you have any.

  - The diffstat given after a merge (or a pull) honors the
    color.diff configuration.

  - "git commit --amend" is now compatible with various message source
    options such as -m/-C/-c/-F.

  - "git-apply --whitespace=strip" removes blank lines added at
    the end of the file.

  - "git-fetch" over git native protocols with "-v" option shows
    connection status, and the IP address of the other end, to
    help diagnosing problems.

  - We used to have core.legacyheaders configuration, when
    set to false, allowed git to write loose objects in a format
    that mimicks the format used by objects stored in packs.  It
    turns out that this was not so useful.  Although we will
    continue to read objects written in that format, we do not
    honor that configuration anymore and create loose objects in
    the legacy/traditional format.

  - "--find-copies-harder" option to diff family can now be
    spelled as "-C -C" for brevity.

  - "git-mailsplit" (hence "git-am") can read from Maildir
    formatted mailboxes.

  - "git-cvsserver" does not barf upon seeing "cvs login"
    request.

  - "pack-objects" honors "delta" attribute set in
    .gitattributes.  It does not attempt to deltify blobs that
    come from paths with delta attribute set to false.

  - "new-workdir" script (in contrib) can now be used with a
    bare repository.

  - "git-mergetool" learned to use gvimdiff.

  - "gitview" (in contrib) has a better blame interface.

  - "git log" and friends did not handle a commit log message
    that is larger than 16kB; they do now.

  - "--pretty=oneline" output format for "git log" and friends
    deals with "malformed" commit log messages that have more
    than one lines in the first paragraph better.  We used to
    show the first line, cutting the title at mid-sentence; we
    concatenate them into a single line and treat the result as
    "oneline".

  - "git p4import" has been demoted to contrib status.  For
    a superior option, checkout the git-p4 front end to
    git-fast-import (also in contrib).  The man page and p4
    rpm have been removed as well.

  - "git mailinfo" (hence "am") now tries to see if the message
    is in utf-8 first, instead of assuming iso-8859-1, if
    incoming e-mail does not say what encoding it is in.

* Builds

  - old-style function definitions (most notably, a function
    without parameter defined with "func()", not "func(void)")
    have been eradicated.

* Performance Tweaks

  - git-pack-objects avoids re-deltification cost by caching
    small enough delta results it creates while looking for the
    best delta candidates.

  - git-pack-objects learned a new heuristcs to prefer delta
    that is shallower in depth over the smallest delta
    possible.  This improves both overall packfile access
    performance and packfile density.

  - diff-delta code that is used for packing has been improved
    to work better on big files.

  - when there are more than one pack files in the repository,
    the runtime used to try finding an object always from the
    newest packfile; it now tries the same packfile as we found
    the object requested the last time, which exploits the
    locality of references.

  - verifying pack contents done by "git fsck --full" got boost
    by carefully choosing the order to verify objects in them.


Fixes since v1.5.2
------------------

All of the fixes in v1.5.2 maintenance series are included in
this release, unless otherwise noted.

* Bugfixes

  - "gitweb" had trouble handling non UTF-8 text with older
    Encode.pm Perl module.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Ismail Dönmez]

On Saturday 04 August 2007 03:28:26 you wrote:
> 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.

Can't build manpages, same error as 
http://lists-archives.org/git/625107-having-problems-with-building-the-manpages.html :

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

Ismail Dönmez <ismail@pardus.org.tr> writes:

> Can't build manpages, same error as ...

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...

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Ismail Dönmez]

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

On Saturday 04 August 2007 04:30:12 Junio C Hamano wrote:
> Ismail Dönmez <ismail@pardus.org.tr> writes:
> > Can't build manpages, same error as ...
>
> 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...

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

Regards,
ismail

-- 
Perfect is the enemy of good

[-- Attachment #2: docbook-xsl-manpages-charmap.patch --]
[-- Type: text/x-diff, Size: 504 bytes --]

--- docbook-xsl-1.73.0/manpages/docbook.xsl.manpages-charmap	2007-07-23 16:24:23.000000000 +0100
+++ docbook-xsl-1.73.0/manpages/docbook.xsl	2007-07-23 16:25:16.000000000 +0100
@@ -37,6 +37,7 @@
   <xsl:include href="lists.xsl"/>
   <xsl:include href="endnotes.xsl"/>
   <xsl:include href="table.xsl"/>
+  <xsl:include href="../common/charmap.xsl"/>
 
   <!-- * we rename the following just to avoid using params with "man" -->
   <!-- * prefixes in the table.xsl stylesheet (because that stylesheet -->

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

Ismail Dönmez <ismail@pardus.org.tr> writes:

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

Thanks.  I'll mention this in the INSTALL document somewhere.

Perhaps the patch should go to docbook-xsl maintainers.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Ismail Dönmez]

On Saturday 04 August 2007 06:13:13 you wrote:
> Ismail Dönmez <ismail@pardus.org.tr> writes:
> > Attached patch from Fedora against docbook-xsl 1.73 fixes the issue.
>
> 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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Steven Grimm]

Junio C Hamano wrote:
> 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.
>   

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

Steven Grimm <koreth@midwinter.com> writes:

> 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.

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
xhtml11 backend, the output is written directly by asciidoc).

> 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?

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 fashion and we
   would want to switch to newer formats?

 * What to do with the user manual, which formats to docbook
   "book" output?

I have a mild suspicion that a clone/fork of AsciiDoc is not a
way to go.

It might be more worthwhile to research what other "Text-ish
lightweight mark-up" systems are availble, and if there is one
that is more efficient and can go to at least html and man,
one-time convert our documentation source to that format using
your Perl magic.  The minimum requirements are:

 * The source is readable without too much mark-up distraction;

 * Can go to roff -man;

 * Can go to html.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Daniel Barkalow]

On Fri, 3 Aug 2007, Junio C Hamano wrote:

> 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).

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*

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

Daniel Barkalow <barkalow@iabervon.org> writes:

> 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).

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.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Daniel Barkalow]

On Fri, 3 Aug 2007, Junio C Hamano wrote:

> Daniel Barkalow <barkalow@iabervon.org> writes:
> 
> > 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).
> 
> 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*

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Steven Grimm]

Junio C Hamano wrote:
> 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).
>   

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 
AsciiDoc -- but it's certainly not all of xmlto.)

>  * 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.
>   

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 
compatibility would be a total non-issue.

>  * 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?
>   

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 
markup we needed.

>  * What would happen when xhtml11 goes out of fashion and we
>    would want to switch to newer formats?
>   

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 
cause AsciiDoc/xmlto to be sufficiently fast!)

>  * What to do with the user manual, which formats to docbook
>    "book" output?
>   

Ah, that's a sticking point, and an answer to my "are there other output 
formats?" question. I never pay attention to that file when I'm doing 
builds -- forgot it even existed. I'll ask one question first: is that 
Docbook output actually necessary, or would people be happy enough just 
having the user manual in XHTML?

Assuming we really need a Docbook manual, it's tempting to say, "keep 
using AsciiDoc" but then my assertion that we aren't really using 
AsciiDoc's input format kind of flies out the window. I wonder if it's 
possible to go from one of my proposed script's *output* formats to 
Docbook format -- is there software to take well-formed XHTML and turn 
it into that format? (Possibly that software is called "xmlto"...) I 
think the transformation from .txt to .html is likely to be pretty 
lossless, so it should be theoretically possible, anyway.

> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
>
>  * The source is readable without too much mark-up distraction;
>
>  * Can go to roff -man;
>
>  * Can go to html.
>   

I will look around and see what I can find. You're quite right, better 
to use already-existing code than reinvent the wheel.

-Steve

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Doug Maxey]

On Sat, 04 Aug 2007 14:11:54 +0800, Steven Grimm wrote:
> 
> I will look around and see what I can find. You're quite right, better 
> to use already-existing code than reinvent the wheel.

/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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Sam Ravnborg]

On Sat, Aug 04, 2007 at 02:11:54PM +0800, Steven Grimm wrote:
> Junio C Hamano wrote:
> >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).
> >  
> 
> 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 
> AsciiDoc -- but it's certainly not all of xmlto.)

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Steven Grimm]

Sam Ravnborg wrote:
> 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.
>   

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Steven Grimm <koreth@midwinter.com> writes:

> Sam Ravnborg wrote:
>> 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.
>>   
>
> 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.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Steven Grimm]

David Kastrup wrote:
> A system such as info, in contrast, is hierarchical, and organized
> with indexes and cross references making it much easier to find
> things.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Johannes Schindelin]

Hi,

On Sun, 5 Aug 2007, Steven Grimm wrote:

> David Kastrup wrote:
> > A system such as info, in contrast, is hierarchical, and organized
> > with indexes and cross references making it much easier to find
> > things.
> 
> 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 see the same.

> Am I alone in my dislike of info, I wonder?

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Steven Grimm <koreth@midwinter.com> writes:

> David Kastrup wrote:
>> A system such as info, in contrast, is hierarchical, and organized
>> with indexes and cross references making it much easier to find
>> things.
>
> 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)

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,
and then to the whole file.

> 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.

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
to get to the git-commit man page equivalent.

> 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?

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Jeff King]

On Sun, Aug 05, 2007 at 12:03:42AM +0800, Steven Grimm wrote:

> 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 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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sat, 4 Aug 2007, David Kastrup wrote:
> 
> A system such as info, in contrast, is hierarchical, and organized
> with indexes and cross references making it much easier to find
> things.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sat, 4 Aug 2007, David Kastrup wrote:
>> 
>> A system such as info, in contrast, is hierarchical, and organized
>> with indexes and cross references making it much easier to find
>> things.
>
> You must be kidding. Texinfo is the worst documentation format EVER.

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
information.

> 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.

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
the plain facts again.

> There are absolutely _zero_ advantages in Texinfo over AsciiDoc.

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
information.

> 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).

So what?

    makeinfo --plaintext

exists.  The important thing for a source file format is that it is
_writeable_.  Restricting a source file format to carry just that kind
of information which can be made to look pretty is a mistake in my
book.

Anyway, here are some sections from AUCTeX's README generated from
readme.texi:

    Introduction to AUCTeX
    **********************

    This file gives a brief overview of what AUCTeX is.  It is *not* an
    attempt to document AUCTeX.  Real documentation for AUCTeX is available
    in the manual, which should be available as an info file after
    installation.

    1 Installation
    **************

    Read the `INSTALL' or `INSTALL.windows' file respectively for
    comprehensive information about how to install AUCTeX.

       The installation routine tries to make the modes provided by AUCTeX
    the default for all supported file types.  If this does not happen in
    your case, add
         (load "auctex.el" nil t t)
       to your init file and consult the section about loading the package
    in the `INSTALL' file.

       If you want to change the modes for which it is operative instead of
    the default, use
         M-x customize-variable RET TeX-modes RET

       If you want to remove a preinstalled AUCTeX completely before any of
    its modes have been used,
         (unload-feature 'tex-site)
       should accomplish that.

       If you are considering upgrading AUCTeX, the recent changes are
    described in the `CHANGES' file.

Actually, the indentation could be prettier if the quote environments
were properly set off as paragraphs.

Anyway, here is the corresponding source (it suffers from the
complications that it is the start of the file, and that the README
can be produced both as a top-level standalone file, as well as a
subordinate chapter in the containing complete documentation).

    @include macros.texi
    @ifset rawfile
    @chapheading Introduction to @AUCTeX{}
    @raisesections
    @end ifset

    @ifclear rawfile
    @node Introduction, Installation, Copying, top
    @chapter Introduction to @AUCTeX{}
    @end ifclear

    @ifset rawfile
    This file
    @end ifset
    @ifclear rawfile
    This section of the @AUCTeX{} manual
    @end ifclear
    gives a brief overview of what @AUCTeX{} is.  It is @strong{not} an
    attempt to document @AUCTeX{}.  Real documentation for @AUCTeX{} is
    available in the
    @ifset rawfile
    manual, which should be available as an info file after installation.
    @end ifset
    @ifclear rawfile
    rest of the manual.
    @end ifclear

    @section Installation

    Read the
    @ifset rawfile
    @file{INSTALL} or @file{INSTALL.windows} file
    @end ifset
    @ifclear rawfile
    section @ref{Installation}, or @ref{Installation under MS Windows},
    @end ifclear
    respectively for comprehensive information about how to install
    @AUCTeX{}.

    The installation routine tries to make the modes provided by @AUCTeX{}
    the default for all supported file types.  If this does not happen in
    your case, add
    @lisp
    (load "auctex.el" nil t t)
    @end lisp
    to your init file and consult the section
    @ifset rawfile
    about loading the package in the @file{INSTALL} file.
    @end ifset
    @ifclear rawfile
    @ref{Loading the package}.
    @end ifclear

    If you want to change the modes for which it is operative instead of the
    default, use
    @example
    @kbd{M-x customize-variable RET TeX-modes RET}
    @end example

    If you want to remove a preinstalled @AUCTeX{} completely before any of
    its modes have been used,
    @example
    (unload-feature 'tex-site)
    @end example
    should accomplish that.

    If you are considering upgrading @AUCTeX{}, the recent changes are
    described in
    @ifset rawfile
    the @file{CHANGES} file.
    @end ifset
    @ifclear rawfile
    @ref{Changes}.
    @end ifclear


This is reasonable writeable, and it contains all the information for
hyperlinking and cross-referencing the stuff.  It is not necessarily
overly pretty, but it can be converted very efficiently both into
single file PDF which can be either navigated on its own or printed,
or into raw text files similar to the existing documentation, or into
HTML or into info, for which efficient _hierarchical_ readers exist.

Now XML certainly has all the expressivity needed to represent the
same information, but you still need a reader that actually makes use
of it.  And you have to have the information also expressed in
AsciiDoc, and the requirement that it still looks good in the _source_
code makes it awkward designing an appropriate ASCII way of
representing the information.

AsciiDoc may have the _potential_ to do the same, but at the current
point of time, I don't see that there are tools for conveniently
navigating hundred-page and longer AsciiDoc documents.  And there are
for Texinfo.

I am fine if you don't like Texinfo and would rather use something
different with the _same_ amount of information content as Texinfo
has, and with readers that make use of it.  Heck, _if_ the source
format can be made to represent the same information, it might be
possible to create Texinfo or at least info pages from it.

Texinfo is not really the point.  It is just there to show that it
_is_ possible to work with documentation that provides a _structured_
view into a _large_, coherent document.  Of course, by far the best
reader for it (or rather the generated info files) is Emacs, and
that's definitely a drawback for those who don't work with it.  The
standalone reader has been sub-par for decades.  At the current point
of time, it may be considered tolerable, but not exciting.  But at
least it exists.

Man pages don't scale to hundreds of pages, and neither does the
current organization of git documentation do this.  If you can propose
something that works at least as well as Texinfo for navigating
hundreds of pages of information, go ahead.

It is not that Texinfo is great.  It is just that I don't see an
alternative that sucks less right now.  Lots of _formats_ would have
potential for it, but the readers for making use of such documentation
are just not there.  And PDF is not really a good alternative, since
fonts, pagination and linear order are not optimized for screen, but
for print.  And of course, it is much slower to display, and has no
up/down navigation, but only forward/back.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sat, 4 Aug 2007, David Kastrup wrote:
> >
> > You must be kidding. Texinfo is the worst documentation format EVER.
> 
> Oh come on.  It was the first hyperlinked and hierarchical format
> before HTML even existed.

Yes. And it should have died after html took its place.

> Actually, a decade ago the Emacs-internal info reader was worse than
> it is now.

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 
"real" emacs to be really disturbing on so many levels ;)

> [ structure ]
>
> And as opposed to AsciiDoc, there _are_ readers that make use of this
> information.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sat, 4 Aug 2007, David Kastrup wrote:
>> >
>> > You must be kidding. Texinfo is the worst documentation format EVER.
>> 
>> Oh come on.  It was the first hyperlinked and hierarchical format
>> before HTML even existed.
>
> Yes. And it should have died after html took its place.

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.
Unfortunately, it has taken a different place up to now.

>> Actually, a decade ago the Emacs-internal info reader was worse
>> than it is now.
>
> 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_?

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
things.  It is quite better now.  Bit it is not Emacs.

> (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 "real" emacs to be really disturbing on so many
> levels ;)
>
>> [ structure ]
>>
>> And as opposed to AsciiDoc, there _are_ readers that make use of
>> this information.
>
> None that any normal user would want to use.

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.

You can't usefully find your way through a hundreds-pages manual page.

> The thing is, html does a much better job of all of that, simply
> because there are useful readers.

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
could ever hope to replicate.

> 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!

For single pages, yes.  For hundreds of pages, this falls apart.  Man
pages don't scale.

> 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.

Again, you presume to know the rest of the world, and the rest of the
world is "normal" and just like you.

I will readily agree with you that for the longest time, reading info
files outside of Emacs was painful enough to make it mostly useless.
With the current standalone info reader, it is merely annoying.

And inside of Emacs (and using Emacs is not as much the equivalent of
doing appendectomy on yourself with a fork because there is no
_equivalent_ to do the same job, but has progressed to a reasonably
sharp knife), info has moved from "tolerable" to "quite usable" under
Emacs 22: you can easily search whole documents, single nodes,
chapters.  Pretty much everything is clickable by mouse (with mouse
button 1), including the structural information that _stays_ on top of
your window.

Anyway, like it or not, the current form of git documentation is not
structured, and that means that it is very hard to get the big
picture.  Texinfo might have readers that suck, but other formats
don't have readers doing the job at all when we are talking about
finding your way in a document of some hundred pages.  PDF at the
current point of time is about the closest you can come, and it is
print-oriented and slow.  And it certainly does not offer something
like typing
i assembl RET
in order to jump through the index at the first page referring to
assembly language.

Like with TeX itself, the scandal is not that decade-old technology is
still in use, but rather that nobody has replaced it with anything
actually doing the same job, in spite of all the information being
freely available and in spite of the old technology being really
arcane.

Find me an HTML reader that allows keypress-based structured
navigation through documents of a few hundred pages, and _then_ talk
about Texinfo being supplanted.

Heck, _nobody_ likes Texinfo, including myself.  It is a stupid format
and not remarkably fun to write or understand.  It is just that there
are no bloody tools doing the same job.  After all these years, and in
spite of a really terrible standalone reader for the longest time.

I can perfectly well understand your lack of enthusiasm.  And feel
free to call me and the FSF and info and who- and whatever else any
name you like (you won't be able to refrain anyhow).  But the fact
remains that the best way to find some information in the current git
documentation is not using HTML.  It is not using man, unless you
already know what you are looking for.

No, currently the _only_ viable search interface into git's
documentation as a whole consists of grep and less.

And for your favorite "normal user" scapegoat, that sucks even worse
than the standalone info reader, let alone Emacs.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[J. Bruce Fields]

On Sat, Aug 04, 2007 at 09:55:48PM +0200, David Kastrup wrote:
> The problem is that html, not even now, offers useful standardized
> structural navigation information,

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.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sat, 4 Aug 2007, David Kastrup wrote:
> >
> > None that any normal user would want to use.
> 
> Linus, do you really think that the editor _you_ use is used by more
> people than Emacs?  Think again.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sat, 4 Aug 2007, David Kastrup wrote:
>> >
>> > None that any normal user would want to use.
>> 
>> Linus, do you really think that the editor _you_ use is used by more
>> people than Emacs?  Think again.
>
> No.
>
> But I'm also not confused enough to think that people should use 
> micro-emacs for reading man-pages.

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
about "normal", "sane", "confused" and so on.

> The UNIX philosophy is "do one thing, and do it well".

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
about.  Not Emacs, but rather documentation formats.

> Man-pages with man.

Actually, Emacs "woman" does a pretty good job with those, offers
convenient man page name completion and works on Windows and similar
platforms without needing

> 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.

Why the hell do you keep changing the topic and go off on sideline
rants.

> That whole "do everything in emacs" is a disease. And then emacs
> users think that it's "sane".

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 text documentation efficiently.  It
may be an _ugly_ application, but instead of saying what you use
instead in your daily workflow, you revert to name-calling.

If you have a _working_ solution to offer for that task, try
presenting it instead of calling people using other tools names.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sun, 5 Aug 2007, David Kastrup wrote:
> 
> So please get a grip and focus on what we were actually talking
> about.  Not Emacs, but rather documentation formats.

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 
crap-ware.

> > Man-pages with man.
> 
> Actually, Emacs "woman" does a pretty good job with those, offers
> convenient man page name completion and works on Windows and similar
> platforms without needing

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 
piece of crap as far as most users are concerned.

> 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)?

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sun, 5 Aug 2007, David Kastrup wrote:
>> 
>> So please get a grip and focus on what we were actually talking
>> about.  Not Emacs, but rather documentation formats.
>
> 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 crap-ware.

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
rather than documentation formats.

> So stop this *insane* insistence of emacs. You should learn to just
> assume that people don't even have it installed!

We were discussing Texinfo, not Emacs.  Please focus.

> Anything that works with some random emacs mode is a total
> non-usable piece of crap as far as most users are concerned.

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
please stop focusing on editors and focus on documentation formats.

>> 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)?
>
> Oh, a single large html page is certainly better than emacs and
> info, absolutely. Ask *any* normal person.

Which is why books nowadays always come as a single scroll without
index and table of contents, right?  Ask any normal person.

> The fact that you cannot see that fact is a sign of your personal
> (and rather odd) preferences.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sun, 5 Aug 2007, David Kastrup wrote:
> 
> You are still unable to focus on anything but name-calling and editors
> rather than documentation formats.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Johannes Schindelin]

Hi,

On Sun, 5 Aug 2007, Linus Torvalds wrote:

> > You are still unable to focus on anything but name-calling and editors 
> > rather than documentation formats.
> 
> No, it's the same thing.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Sun, 5 Aug 2007, Linus Torvalds wrote:
>
>> > You are still unable to focus on anything but name-calling and editors 
>> > rather than documentation formats.
>> 
>> No, it's the same thing.
>
> Hehe.  Statements like the first made me set up a certain procmail
> filter.  Made me much happier, too.

Interesting stance for somebody who has complained violently that I
should provide him with personal copies of mails to the list.  So you
need those copies in order to keep your procmail busy...

> 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*

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sun, 5 Aug 2007, David Kastrup wrote:
>> 
>> You are still unable to focus on anything but name-calling and editors
>> rather than documentation formats.
>
> 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.

No, that's not what makes it horrible.

> The only thing it buys you (the "info" format) is totally
> irrelevant, which I tried to explain.

By calling everybody names that would dare using it.  That's not
really an explanation.

> 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.

Readable plain text can be generated from Texinfo, so that is a red
herring.

> 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, 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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Linus Torvalds <torvalds@linux-foundation.org> writes:
>
>> 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, 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.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Linus Torvalds]

On Sun, 5 Aug 2007, David Kastrup wrote:
>
> > The fact that you cannot see that fact is a sign of your personal
> > (and rather odd) preferences.
> 
> Yes, name-calling and ad hominem attacks again.

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 
emacs issues.

> 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.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Bruce Korb]

Linus Torvalds wrote:
>> Yes, name-calling and ad hominem attacks again.
> 
> No. Emacs _is_ odd. It's not even installed by default on most modern 
> Linux distributions.

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
every few years.  I've been a happy emacs user for 24 years.

> There's no name-calling there. That's just a solid fact.

The name calling is unseemly on all sides.

>> 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.
> 
> 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!

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
not degenerate into nasty name calling.

> Headers? Lists? They look like headers and lists in the .txt files. No 
> need to think about it as a reader. 

So do well-formatted .texi docs.  I don't really like anything
other than WYSIWYG, but that doesn't lend it self to reformatting
into man pages et al.

> 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*.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Bruce Korb <bkorb@gnu.org> writes:

> Linus Torvalds wrote:
>
>> AsciiDoc is *also* a source format. But the source format is
>> already readable IN ITSELF. Which is the whole point!
>
> Readable, just not writable.  It's markup language is a bunch of
> special characters that require familiarity to understand.

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 straightforward enough to write additional
converters if one wants to (makeinfo can even produce Docbook output,
so perhaps I may have a chance to reverse-engineer some required
information from there).

Whatever.  It is pretty clear that Texinfo is not going to be
interesting enough to maintain for most git developers to continue
this particular thread, as it won't progress beyond a simple and ugly
advocacy and name-calling thread.

Anyway, the necessary structural information (indexing, directory info
etc) presumably can be spliced into Asciidoc documents once somebody
finds out how to do this, and then Texinfo can be _generated_ from it
for those who need it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[J. Bruce Fields]

On Mon, Aug 06, 2007 at 12:15:24AM +0200, David Kastrup wrote:
> Or things like including the manual pages in an appendix or elsewhere.
> Any chance for that?  Slim, at least for me.

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.

Man-pages in user manual (was: [ANNOUNCE] GIT 1.5.3-rc4)

[David Kastrup]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> On Mon, Aug 06, 2007 at 12:15:24AM +0200, David Kastrup wrote:
>> Or things like including the manual pages in an appendix or elsewhere.
>> Any chance for that?  Slim, at least for me.
>
> 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.

Well, I posted already a patch set (or rather, several iterations)
that built info documentation from the user manual.  I only got a
single comment from Jakub about notices in INSTALL, and about the awk
dependency.  The last iteration from yesterday addressed both AFAICT.
Since it does not affect existing Makefile targets at all, I hope that
it may end up in 1.5.3.

However, independently from info, I think the git documentation should
be structured into one or more standalone documents that make sense as
a single DocBook document (and ultimately a printed PDF) each.  Of
course this will benefit generating info, but it will also give other
people better documentation into their hands.

I digress.

Concerning your request

> If someone had the time to look into what would be required to get
> it working, I'd be grateful.

I did some digging and some trying.  The inclusion of the manual pages
will not work out of the box: they have different markup and logical
sectioning levels.

However, AsciiDoc does provide mechanisms that could be used for
including this sort of stuff, by just matching the markup used in the
man page sources and replacing it with the appropriate headers or
markup for the DocBook case.

To figure this out, read up on the following parts:
<URL:http://www.methods.co.nz/asciidoc/userguide.html#toc67>
<URL:http://www.methods.co.nz/asciidoc/userguide.html#toc71>
<URL:http://www.methods.co.nz/asciidoc/userguide.html#toc75>

It turns out, however, that this may be doing it the hard way: There
is a way to have sections/appendices consisting of just manual pages:

<URL:http://www2.informatik.hu-berlin.de/~draheim/doc/docbook-manpages.html>

So it may be easiest to just create a <reference> section in the XML,
include the man pages in there, and see what the various DocBook
converters make of that.

Of course, in such a document one would want to change the gitlink
macros to actually point to the included reference rather than an
outside resource.

That would have to be done in Documentation/asciidoc.conf as far as I
can see.

There are already autogenerated files cmds*.txt that contain lists of
the various manpages.  One could either use them directly (with a
temporary gitlink definition that includes a manual page rather than
referring to it), or generate similar files with a more
straightforward relation of content and behavior.

-- 
David Kastrup

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Junio C Hamano]

David Kastrup <dak@gnu.org> writes:

>> So stop this *insane* insistence of emacs. You should learn to just
>> assume that people don't even have it installed!
>
> We were discussing Texinfo, not Emacs.  Please focus.

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.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Miles Bader]

Junio C Hamano <gitster@pobox.com> writes:
> 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.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Junio C Hamano <gitster@pobox.com> writes:

> David Kastrup <dak@gnu.org> writes:
>
>>> So stop this *insane* insistence of emacs. You should learn to just
>>> assume that people don't even have it installed!
>>
>> We were discussing Texinfo, not Emacs.  Please focus.
>
> 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.

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
to guess from the information just how.

> 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.

    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
    mode commands.  (*Note Updating Nodes and Menus::.)

> There is no good editor to help you maintain them other than Emacs
> texinfo mode as far as I know.

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 is documented.

In contrast, I have just tried using makeinfo --docbook on AUCTeX
Texinfo documentation, and the docbook XML it produces is not always
properly nested, and when one corrects that, the problems with
processing that just start: that seems not really tested, at least
with makeinfo 4.8.

So there is a good Docbook->info path, but not the other way round.
Anyway, you wrote:

> I would welcome if the set of our documentation output formats
> included *.info pages.

At least for the user manual, I can support this (without index) in a
dozen lines of makefile code and another dozen lines of sed (for
adding the top/dir entry information).  Yes, this caught me quite by
surprise.  For the indexing, of course one will have to insert the
appropriate Asciidoc markup into the source files.  I can also work on
that, but it should likely be a colloborative effort: it leads to a
working Index also in the PDF output without the need to involve
Texinfo.

As for making the man pages part of the main manual: I don't know my
way around Asciidoc enough to be able to do this.  It might be
possible to fudge around this issue with sed again, converting the
manual page sources to book section sources.  I am sure there is a
more elegant way to do this sort of transformation/conversion either
on the Asciidoc or XML level, but it's beyond me.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Jeff King]

On Sat, Aug 04, 2007 at 07:49:36PM +0200, David Kastrup wrote:

> 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.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sat, Aug 04, 2007 at 07:49:36PM +0200, David Kastrup wrote:
>
>> 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.
>
> Ugh. A documentation referencing system that works only in one
> particular editor,

That works in readers of the info format.  Do HTML references work
outside of HTML readers?

> or with one particular documentation format?
>
> Please, the net decided on a standard for referencing resources long
> ago, and they are called URLs.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Jeff King]

On Sun, Aug 05, 2007 at 11:54:51AM +0200, David Kastrup wrote:

> >> (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.
> >
> > Ugh. A documentation referencing system that works only in one
> > particular editor,
> 
> That works in readers of the info format.  Do HTML references work
> outside of HTML readers?

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sun, Aug 05, 2007 at 11:54:51AM +0200, David Kastrup wrote:
>
>> >> (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.
>> >
>> > Ugh. A documentation referencing system that works only in one
>> > particular editor,
>> 
>> That works in readers of the info format.  Do HTML references work
>> outside of HTML readers?
>
> 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).

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
about URLs.

> 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.

Sure.  So use the above syntax.

> 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.

So write it as a URL, if you want to.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Jeff King]

On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:

> Well, just for kicks I let firefox loose on
> 
> info:gcc#Extended Asm

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

-Peff

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:
>
>> Well, just for kicks I let firefox loose on
>> 
>> info:gcc#Extended Asm
>
> OK, I didn't know there was a URL style defined for info.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Jeff King <peff@peff.net> writes:
>
>> On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:
>>
>>> Well, just for kicks I let firefox loose on
>>> 
>>> info:gcc#Extended Asm
>>
>> OK, I didn't know there was a URL style defined for info.
>
> Neither did I, actually.  If anybody would actually use them, I'd have
> to teach firefox to pass them off to Emacs.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Johannes Schindelin]

Hi,

On Sat, 4 Aug 2007, Steven Grimm wrote:

> Junio C Hamano wrote:
>
> >  * 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?
> >   
> 
> 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".

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[J. Bruce Fields]

On Sat, Aug 04, 2007 at 12:38:35PM +0100, Johannes Schindelin wrote:
> 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.

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.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kastrup]

Junio C Hamano <gitster@pobox.com> writes:

> Steven Grimm <koreth@midwinter.com> writes:
>
>> 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?
>
> 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.

[...]

> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
>
>  * The source is readable without too much mark-up distraction;
>
>  * Can go to roff -man;
>
>  * Can go to html.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Timo Hirvonen]

Junio C Hamano <gitster@pobox.com> wrote:

> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
> 
>  * The source is readable without too much mark-up distraction;
> 
>  * Can go to roff -man;
> 
>  * Can go to html.

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=8ab4e92a6356d9cca0d738130fe54026da8c690b;hb=54b6ddacd9d1387c256ce5e7d7d8bb3324799c04

It might be quite easy to extend ttman to output html too...

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Johannes Schindelin]

Hi,

On Sat, 4 Aug 2007, Timo Hirvonen wrote:

> Junio C Hamano <gitster@pobox.com> wrote:
> 
> > It might be more worthwhile to research what other "Text-ish
> > lightweight mark-up" systems are availble, and if there is one
> > that is more efficient and can go to at least html and man,
> > one-time convert our documentation source to that format using
> > your Perl magic.  The minimum requirements are:
> > 
> >  * The source is readable without too much mark-up distraction;
> > 
> >  * Can go to roff -man;
> > 
> >  * Can go to html.
> 
> I used asciidoc too but it was really PITA to install and use

I disagree.  Whenever I had the need, installing asciidoc was pretty 
swift.  No problems at all.

> so I wrote a small tool (ttman) in C which converts .txt files directly 
> to man pages.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Timo Hirvonen]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

> Hi,
> 
> On Sat, 4 Aug 2007, Timo Hirvonen wrote:
> 
> > I used asciidoc too but it was really PITA to install and use
> 
> I disagree.  Whenever I had the need, installing asciidoc was pretty 
> swift.  No problems at all.

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
wouldn't be surprised if it couldn't build the GIT documentation.

> > so I wrote a small tool (ttman) in C which converts .txt files directly 
> > to man pages.
> 
> 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,

I've never liked parser generators.

> 	- it looks like a perl script doing the same job would have been 
> 	  even smaller yet, and

Very likely but perl is incompatible with my brain :)

> 	- the syntax is nowhere near asciidoc syntax.

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
perl hacker to write the script.

> For official releases, I'd still want to rely on asciidoc.

Agreed, rushing to change the documentation format wouldn't be wise.

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Michael]

On Saturday 04 August 2007 06:38, Junio C Hamano wrote:
> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
> 
>  * The source is readable without too much mark-up distraction;
> 
>  * Can go to roff -man;
> 
>  * Can go to html.

I know about txt2tags, but I'm not sure it will be the right choice.

http://txt2tags.sourceforge.net/

It's in python, uses a markup similar to wiki, and can be used to
create documentation in man, html, plain txt.

But I haven't used it very much.

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Robin Rosenberg]

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[Julian Phillips]

On Sat, 4 Aug 2007, Robin Rosenberg wrote:

>
> 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

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

Re: [ANNOUNCE] GIT 1.5.3-rc4

[David Kågedal]

Junio C Hamano <gitster@pobox.com> writes:

> 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.

This will not make sense to a lot of people.  I've been around here
since git was invented, and I think I can guess what it means, but I'm
not completely sure.  A "commit walker" is something that probably
only a few core git developers know what it is.

Please remember to give a second of thought to who will be reading
this.  It is very hard to determine from this short message who will
be affected, and in what way.

-- 
David Kågedal