{"thread":{"id":"9373","subject":"[ANNOUNCE] GIT 1.5.3-rc4","startedAt":"2007-08-04T00:28:26Z","lastAt":"2007-08-08T08:11:22Z","messageCount":59,"participants":["Junio C Hamano","Ismail Dönmez","Steven Grimm","Daniel Barkalow","Doug Maxey","David Kastrup","Sam Ravnborg","Timo Hirvonen","Johannes Schindelin","Robin Rosenberg","Julian Phillips","J. Bruce Fields","Michael","Linus Torvalds","Jeff King","Bruce Korb","Miles Bader","David Kågedal"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"49650","messageId":"7vzm18jg7p.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":null,"subject":"[ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-04T00:28:26Z","receivedAt":"2007-08-04T00:28:26Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I tagged 1.5.3-rc4 and it will soon be mirrored out. This is\nthe last rc before the real thing, which I am hoping to happen\nby mid August. Until then, I won't look at anything but\nregression fixes and documentation updates. Please test this\none well.\n\n http://www.kernel.org/pub/software/scm/git/\n\n git-1.5.3-rc4.tar.{gz,bz2}\t\t\t(tarball)\n git-htmldocs-1.5.3-rc4.tar.{gz,bz2}\t\t(preformatted docs)\n git-manpages-1.5.3-rc4.tar.{gz,bz2}\t\t(preformatted docs)\n testing/git-*-1.5.3-rc4-1.$arch.rpm\t\t(RPM)\n\n----------------------------------------------------------------\n\nGIT v1.5.3 Release Notes (draft)\n========================\n\nUpdates since v1.5.2\n--------------------\n\n* The commit walkers other than http are officially deprecated,\n but still supported for now.\n\n* The submodule support has Porcelain layer.\n\n* There are a handful pack-objects changes to help you cope better\n with repositories with pathologically large blobs in them.\n\n* For people who need to import from Perforce, a front-end for\n fast-import is in contrib/fast-import/.\n\n* Comes with git-gui 0.8.0.\n\n* Comes with updated gitk.\n\n* New commands and options.\n\n - \"git log --date=\" can use more formats: iso8601, rfc2822.\n\n - The hunk header output from \"git diff\" family can be customized\n with the attributes mechanism. See gitattributes(5) for details.\n\n - \"git stash\" allows you to quickly save away your work in\n progress and replay it later on an updated state.\n\n - \"git rebase\" learned an \"interactive\" mode that let you\n pick and reorder which commits to rebuild.\n\n - \"git fsck\" can save its findings in $GIT_DIR/lost-found, without a\n separate invocation of \"git lost-found\" command. The blobs stored by\n lost-found are stored in plain format to allow you to grep in them.\n\n - $GIT_WORK_TREE environment variable can be used together with\n $GIT_DIR to work in a subdirectory of a working tree that is\n not located at \"$GIT_DIR/..\".\n\n - Giving \"--file=\" option to \"git config\" is the same as\n running the command with GIT_CONFIG= environment.\n\n - \"git log\" learned a new option \"--follow\", to follow\n renaming history of a single file.\n\n - \"git-filter-branch\" lets you rewrite the revision history of\n specified branches. You can specify a number of filters to\n modify the commits, files and trees.\n\n - \"git-cvsserver\" learned new options (--base-path, --export-all,\n --strict-paths) inspired by git-daemon.\n\n - \"git daemon --base-path-relaxed\" can help migrating a repository URL\n that did not use to use --base-path to use --base-path.\n\n - \"git-commit\" can use \"-t templatefile\" option and commit.template\n configuration variable to prime the commit message given to you in the\n editor.\n\n - \"git-submodule\" command helps you manage the projects from\n the superproject that contain them.\n\n - In addition to core.compression configuration option,\n core.loosecompression and pack.compression options can\n independently tweak zlib compression levels used for loose\n and packed objects.\n\n - \"git-ls-tree -l\" shows size of blobs pointed at by the\n tree entries, similar to \"/bin/ls -l\".\n\n - \"git-rev-list\" learned --regexp-ignore-case and\n --extended-regexp options to tweak its matching logic used\n for --grep fitering.\n\n - \"git-describe --contains\" is a handier way to call more\n obscure command \"git-name-rev --tags\".\n\n - \"git gc --aggressive\" tells the command to spend more cycles\n to optimize the repository harder.\n\n - \"git repack\" learned a \"window-memory\" limit which\n dynamically reduces the window size to stay within the\n specified memory usage.\n\n - \"git repack\" can be told to split resulting packs to avoid\n exceeding limit specified with \"--max-pack-size\".\n\n - \"git fsck\" gained --verbose option. This is really really\n verbose but it might help you identify exact commit that is\n corrupt in your repository.\n\n - \"git format-patch\" learned --numbered-files option. This\n may be useful for MH users.\n\n - \"git format-patch\" learned format.subjectprefix configuration\n variable, which serves the same purpose as \"--subject-prefix\"\n option.\n\n - \"git tag -n -l\" shows tag annotations while listing tags.\n\n - \"git cvsimport\" can optionally use the separate-remote layout.\n\n - \"git blame\" can be told to see through commits that change\n whitespaces and indentation levels with \"-w\" option.\n\n - \"git send-email\" can be told not to thread the messages when\n sending out more than one patches.\n\n - \"git config\" learned NUL terminated output format via -z to\n help scripts.\n\n - \"git init -q\" makes the command quieter.\n\n* Updated behavior of existing commands.\n\n - \"gitweb\" can offer multiple snapshot formats.\n\n ***NOTE*** Unfortunately, this changes the format of the\n $feature{snapshot}{default} entry in the per-site\n configuration file 'gitweb_config.perl'. It used to be a\n three-element tuple that describe a single format; with the\n new configuration item format, you only have to say the name\n of the format ('tgz', 'tbz2' or 'zip'). Please update the\n your configuration file accordingly.\n\n - \"git diff\" (but not the plumbing level \"git diff-tree\") now\n recursively descends into trees by default.\n\n - The editor to use with many interactive commands can be\n overridden with GIT_EDITOR environment variable, or if it\n does not exist, with core.editor configuration variable. As\n before, if you have neither, environment variables VISUAL\n and EDITOR are consulted in this order, and then finally we\n fall back on \"vi\".\n\n - \"git rm --cached\" does not complain when removing a newly\n added file from the index anymore.\n\n - Options to \"git log\" to affect how --grep/--author options look for\n given strings now have shorter abbreviations. -i is for ignore case,\n and -E is for extended regexp.\n\n - \"git svn dcommit\" retains local merge information.\n\n - \"git config\" to set values also honors type flags like --bool\n and --int.\n\n - core.quotepath configuration can be used to make textual git\n output to emit most of the characters in the path literally.\n\n - \"git mergetool\" chooses its backend more wisely, taking\n notice of its environment such as use of X, Gnome/KDE, etc.\n\n - \"gitweb\" shows merge commits a lot nicer than before. The\n default view uses more compact --cc format, while the UI\n allows to choose normal diff with any parent.\n\n - snapshot files \"gitweb\" creates from a repository at\n $path/$project/.git are more useful. We use $project part\n in the filename, which we used to discard.\n\n - \"git cvsimport\" creates lightweight tags; there is no\n interesting information we can record in an annotated tag,\n and the handcrafted ones the old code created was not\n properly formed anyway.\n\n - \"git-push\" pretends that you immediately fetched back from\n the remote by updating corresponding remote tracking\n branches if you have any.\n\n - The diffstat given after a merge (or a pull) honors the\n color.diff configuration.\n\n - \"git commit --amend\" is now compatible with various message source\n options such as -m/-C/-c/-F.\n\n - \"git-apply --whitespace=strip\" removes blank lines added at\n the end of the file.\n\n - \"git-fetch\" over git native protocols with \"-v\" option shows\n connection status, and the IP address of the other end, to\n help diagnosing problems.\n\n - We used to have core.legacyheaders configuration, when\n set to false, allowed git to write loose objects in a format\n that mimicks the format used by objects stored in packs. It\n turns out that this was not so useful. Although we will\n continue to read objects written in that format, we do not\n honor that configuration anymore and create loose objects in\n the legacy/traditional format.\n\n - \"--find-copies-harder\" option to diff family can now be\n spelled as \"-C -C\" for brevity.\n\n - \"git-mailsplit\" (hence \"git-am\") can read from Maildir\n formatted mailboxes.\n\n - \"git-cvsserver\" does not barf upon seeing \"cvs login\"\n request.\n\n - \"pack-objects\" honors \"delta\" attribute set in\n .gitattributes. It does not attempt to deltify blobs that\n come from paths with delta attribute set to false.\n\n - \"new-workdir\" script (in contrib) can now be used with a\n bare repository.\n\n - \"git-mergetool\" learned to use gvimdiff.\n\n - \"gitview\" (in contrib) has a better blame interface.\n\n - \"git log\" and friends did not handle a commit log message\n that is larger than 16kB; they do now.\n\n - \"--pretty=oneline\" output format for \"git log\" and friends\n deals with \"malformed\" commit log messages that have more\n than one lines in the first paragraph better. We used to\n show the first line, cutting the title at mid-sentence; we\n concatenate them into a single line and treat the result as\n \"oneline\".\n\n - \"git p4import\" has been demoted to contrib status. For\n a superior option, checkout the git-p4 front end to\n git-fast-import (also in contrib). The man page and p4\n rpm have been removed as well.\n\n - \"git mailinfo\" (hence \"am\") now tries to see if the message\n is in utf-8 first, instead of assuming iso-8859-1, if\n incoming e-mail does not say what encoding it is in.\n\n* Builds\n\n - old-style function definitions (most notably, a function\n without parameter defined with \"func()\", not \"func(void)\")\n have been eradicated.\n\n* Performance Tweaks\n\n - git-pack-objects avoids re-deltification cost by caching\n small enough delta results it creates while looking for the\n best delta candidates.\n\n - git-pack-objects learned a new heuristcs to prefer delta\n that is shallower in depth over the smallest delta\n possible. This improves both overall packfile access\n performance and packfile density.\n\n - diff-delta code that is used for packing has been improved\n to work better on big files.\n\n - when there are more than one pack files in the repository,\n the runtime used to try finding an object always from the\n newest packfile; it now tries the same packfile as we found\n the object requested the last time, which exploits the\n locality of references.\n\n - verifying pack contents done by \"git fsck --full\" got boost\n by carefully choosing the order to verify objects in them.\n\n\nFixes since v1.5.2\n------------------\n\nAll of the fixes in v1.5.2 maintenance series are included in\nthis release, unless otherwise noted.\n\n* Bugfixes\n\n - \"gitweb\" had trouble handling non UTF-8 text with older\n Encode.pm Perl module.\n"},{"id":"49653","messageId":"200708040341.36147.ismail@pardus.org.tr","threadId":"9373","inReplyTo":"7vzm18jg7p.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Ismail Dönmez","fromEmail":"ismail@pardus.org.tr","sentAt":"2007-08-04T00:41:36Z","receivedAt":"2007-08-04T00:41:36Z","isPatch":false,"sender":{"key":"ismail@pardus.org.tr","avatar":null},"body":"On Saturday 04 August 2007 03:28:26 you wrote:\n> I tagged 1.5.3-rc4 and it will soon be mirrored out. This is\n> the last rc before the real thing, which I am hoping to happen\n> by mid August. Until then, I won't look at anything but\n> regression fixes and documentation updates. Please test this\n> one well.\n\nCan't build manpages, same error as \nhttp://lists-archives.org/git/625107-having-problems-with-building-the-manpages.html :\n\nxmlto -m callouts.xsl man git-add.xml\nruntime error: file \nfile:///usr/share/sgml/docbook/xsl-stylesheets-1.73.0/manpages/other.xsl line \n129 element call-template\nThe called template 'read-character-map' was not found.\n\nRegards,\nismail\n\n-- \nPerfect is the enemy of good\n"},{"id":"49656","messageId":"7vsl70jdcr.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":"200708040341.36147.ismail@pardus.org.tr","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-04T01:30:12Z","receivedAt":"2007-08-04T01:30:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ismail Dönmez writes:\n\n> Can't build manpages, same error as ...\n\nSigh...\n\nThe asciidoc toolchain used by us (either AsciiDoc 7 nor 8) does\nnot seem to work well with docbook-xsl 1.72 and 1.73, it seems.\n\nIf you can investigate where the breakage is to come up with\npatches to make it format with newer docbook-xsl, without\nbreaking 1.71 (which k.org uses to make the preformatted\ndocumentation in html and man branches), it would be very much\nwelcomed and appreciated.\n\nI however have a slight suspition that the patch might end up to\nbe against either asciidoc or docbook-xsl package, not our\ndocumentation...\n"},{"id":"49657","messageId":"200708040448.56611.ismail@pardus.org.tr","threadId":"9373","inReplyTo":"7vsl70jdcr.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Ismail Dönmez","fromEmail":"ismail@pardus.org.tr","sentAt":"2007-08-04T01:48:56Z","receivedAt":"2007-08-04T01:48:56Z","isPatch":false,"sender":{"key":"ismail@pardus.org.tr","avatar":null},"body":"On Saturday 04 August 2007 04:30:12 Junio C Hamano wrote:\n> Ismail Dönmez writes:\n> > Can't build manpages, same error as ...\n>\n> Sigh...\n>\n> The asciidoc toolchain used by us (either AsciiDoc 7 nor 8) does\n> not seem to work well with docbook-xsl 1.72 and 1.73, it seems.\n>\n> If you can investigate where the breakage is to come up with\n> patches to make it format with newer docbook-xsl, without\n> breaking 1.71 (which k.org uses to make the preformatted\n> documentation in html and man branches), it would be very much\n> welcomed and appreciated.\n>\n> I however have a slight suspition that the patch might end up to\n> be against either asciidoc or docbook-xsl package, not our\n> documentation...\n\nAttached patch from Fedora against docbook-xsl 1.73 fixes the issue.\n\nRegards,\nismail\n\n-- \nPerfect is the enemy of good\n\n\n--- docbook-xsl-1.73.0/manpages/docbook.xsl.manpages-charmap\t2007-07-23 16:24:23.000000000 +0100\n+++ docbook-xsl-1.73.0/manpages/docbook.xsl\t2007-07-23 16:25:16.000000000 +0100\n@@ -37,6 +37,7 @@\n \n \n \n+ \n \n \n \n"},{"id":"49658","messageId":"7vodhoj8l2.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":"200708040448.56611.ismail@pardus.org.tr","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-04T03:13:13Z","receivedAt":"2007-08-04T03:13:13Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ismail Dönmez writes:\n\n> Attached patch from Fedora against docbook-xsl 1.73 fixes the issue.\n\nThanks. I'll mention this in the INSTALL document somewhere.\n\nPerhaps the patch should go to docbook-xsl maintainers.\n"},{"id":"49659","messageId":"46B3F762.1050306@midwinter.com","threadId":"9373","inReplyTo":"7vsl70jdcr.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2007-08-04T03:49:54Z","receivedAt":"2007-08-04T03:49:54Z","isPatch":false,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"Junio C Hamano wrote:\n> The asciidoc toolchain used by us (either AsciiDoc 7 nor 8) does\n> not seem to work well with docbook-xsl 1.72 and 1.73, it seems.\n> \n\nHow attached are we to asciidoc? Every time I do a clean build and sit \nthere twiddling my thumbs waiting for xmlto to do its thing, I think to \nmyself, \"If this were a dedicated Perl script to do the syntax \ntransformations directly to man and html formats, it would blast through \nall the .txt files in a second or two total.\" It seems outlandish to me \nthat it takes longer to build the (relatively small) documentation than \nit does to build the actual code. Plus we constantly run into this sort \nof problem.\n\nDo we want to keep using asciidoc (e.g., so people can easily export to \nother asciidoc-supported formats), or is a dedicated renderer something \nwe'd consider switching to? I have a flight from China back to the US \ncoming in a couple weeks; this could be a perfect little project to keep \nme occupied between in-flight movies. It doesn't look like the syntax \ntransformations are very hard, and it'd be easy enough to verify \ncorrectness by just comparing against the existing asciidoc output.\n\nAm I correct in observing that \"*roff -man\" and HTML are the only two \noutput formats we care about, or do people use other formats in their \nprivate branches?\n\n-Steve\n"},{"id":"49660","messageId":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":"46B3F762.1050306@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-04T04:38:08Z","receivedAt":"2007-08-04T04:38:08Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Steven Grimm writes:\n\n> How attached are we to asciidoc? Every time I do a clean build and sit\n> there twiddling my thumbs waiting for xmlto to do its thing, I think\n> to myself, \"If this were a dedicated Perl script to do the syntax\n> transformations directly to man and html formats, it would blast\n> through all the .txt files in a second or two total.\" It seems\n> outlandish to me that it takes longer to build the (relatively small)\n> documentation than it does to build the actual code. Plus we\n> constantly run into this sort of problem.\n\nI cannot say that I am really happy with the current situation.\nIn my unscientific tests, it appears that we are spending about\n50% of the time in asciidoc and 50% in xmlto for man backend\n(total about 5 seconds for producing git.7 on my private box).\nFor xhtml11 backend, git.html takes about 2.3 seconds (for\nxhtml11 backend, the output is written directly by asciidoc).\n\n> Do we want to keep using asciidoc (e.g., so people can easily export\n> to other asciidoc-supported formats), or is a dedicated renderer\n> something we'd consider switching to? I have a flight from China back\n> to the US coming in a couple weeks; this could be a perfect little\n> project to keep me occupied between in-flight movies. It doesn't look\n> like the syntax transformations are very hard, and it'd be easy enough\n> to verify correctness by just comparing against the existing asciidoc\n> output.\n>\n> Am I correct in observing that \"*roff -man\" and HTML are the only two\n> output formats we care about, or do people use other formats in their\n> private branches?\n\nI obviously do not speak for others, but the only format I care\nabout personally is the *.txt one. We picked asciidoc primarily\nbecause the source language was readable.\n\nUnfortunately, AsciiDoc 8 requires authors to quote more\n\"special characters\" we would rather be able to use as literals\n(most importantly, plus sign '+') than AsciiDoc 7, and I am\nafraid the trend to hijack more non alphabet letters as\n\"special\" may continue.\n\nIf I read you correctly, what you are proposing to offer is a\nclone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man\nbackends. It is a subset in the sense that you will do only two\nbackends, but otherwise is a clone in the sense that you are\ngoing to implement the input language we use (one thing I\npersonally care about while probably other people do not is the\nconditional compilation \"ifdef::stalenotes[]\" in git.txt).\n\nThere is an obvious maintenance cost and risk with such a fork.\n\n * You would need to duplicate the AsciiDoc 7 manual and\n maintain it as well; otherwise, when later versions of\n AsciiDoc comes, people who update our documentation will\n refer to asciidoc website to learn the syntax, and find out\n that your dialect does not match what is described there.\n This already is the case, as our documentation source is\n written for AsciiDoc 7 and we use asciidoc7compatible support\n when running with AsciiDoc 8.\n\n * How much can we really rely on your fork to be kept\n maintained? When we need newer mark-up that is not offered\n by AsciiDoc 7 clone, is it our plan to model that after\n AsciiDoc X (X > 7), or we just come up with an extension of\n our own?\n\n * What would happen when xhtml11 goes out of fashion and we\n would want to switch to newer formats?\n\n * What to do with the user manual, which formats to docbook\n \"book\" output?\n\nI have a mild suspicion that a clone/fork of AsciiDoc is not a\nway to go.\n\nIt might be more worthwhile to research what other \"Text-ish\nlightweight mark-up\" systems are availble, and if there is one\nthat is more efficient and can go to at least html and man,\none-time convert our documentation source to that format using\nyour Perl magic. The minimum requirements are:\n\n * The source is readable without too much mark-up distraction;\n\n * Can go to roff -man;\n\n * Can go to html.\n"},{"id":"49661","messageId":"Pine.LNX.4.64.0708040046400.23671@iabervon.org","threadId":"9373","inReplyTo":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2007-08-04T04:57:03Z","receivedAt":"2007-08-04T04:57:03Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Fri, 3 Aug 2007, Junio C Hamano wrote:\n\n> If I read you correctly, what you are proposing to offer is a\n> clone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man\n> backends. It is a subset in the sense that you will do only two\n> backends, but otherwise is a clone in the sense that you are\n> going to implement the input language we use (one thing I\n> personally care about while probably other people do not is the\n> conditional compilation \"ifdef::stalenotes[]\" in git.txt).\n\nIt's worth noting that we're a substantial portion of the asciidoc user \nbase, at least based on asciidoc's \"Projects using AsciiDoc\" page. We \ncould probably be influential in the asciidoc development if we tried \n(maybe starting with a config file mechanism for controlling what \ncharacters are markup instead of literal, so that we'll be able to make \ndocuments which will work the same with all versions of asciidoc).\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"49663","messageId":"7v1wejj2j8.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":"Pine.LNX.4.64.0708040046400.23671@iabervon.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-04T05:23:55Z","receivedAt":"2007-08-04T05:23:55Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Daniel Barkalow writes:\n\n> It's worth noting that we're a substantial portion of the asciidoc user \n> base, at least based on asciidoc's \"Projects using AsciiDoc\" page. We \n> could probably be influential in the asciidoc development if we tried \n> (maybe starting with a config file mechanism for controlling what \n> characters are markup instead of literal, so that we'll be able to make \n> documents which will work the same with all versions of asciidoc).\n\nTempting, but...\n\n * The breakage that triggered this thread was not about asciidoc\n but about docbook-xsl. AsciiDoc project cannot do much about\n it.\n\n * The slowness while formatting our manual pages are 50% from\n xmlto toolchain and even if AsciiDoc were were to be sped up\n 20x, we will still spend 4-5 minutes to format ~140 manual\n pages.\n"},{"id":"49668","messageId":"Pine.LNX.4.64.0708040133500.23671@iabervon.org","threadId":"9373","inReplyTo":"7v1wejj2j8.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2007-08-04T05:52:39Z","receivedAt":"2007-08-04T05:52:39Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Fri, 3 Aug 2007, Junio C Hamano wrote:\n\n> Daniel Barkalow writes:\n> \n> > It's worth noting that we're a substantial portion of the asciidoc user \n> > base, at least based on asciidoc's \"Projects using AsciiDoc\" page. We \n> > could probably be influential in the asciidoc development if we tried \n> > (maybe starting with a config file mechanism for controlling what \n> > characters are markup instead of literal, so that we'll be able to make \n> > documents which will work the same with all versions of asciidoc).\n> \n> Tempting, but...\n> \n> * The breakage that triggered this thread was not about asciidoc\n> but about docbook-xsl. AsciiDoc project cannot do much about\n> it.\n> \n> * The slowness while formatting our manual pages are 50% from\n> xmlto toolchain and even if AsciiDoc were were to be sped up\n> 20x, we will still spend 4-5 minutes to format ~140 manual\n> pages.\n\nFor the latter, asciidoc ought to be able to generate manpages. Not sure \nwhat to do about docbook (for the user manual); it seems generally prone \nto compatibility problems. Perhaps we should go through latex instead, \nsince that's extremely stable these days, or go straight to html.\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"49670","messageId":"46B418AA.4070701@midwinter.com","threadId":"9373","inReplyTo":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2007-08-04T06:11:54Z","receivedAt":"2007-08-04T06:11:54Z","isPatch":false,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"Junio C Hamano wrote:\n> If I read you correctly, what you are proposing to offer is a\n> clone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man\n> backends. It is a subset in the sense that you will do only two\n> backends, but otherwise is a clone in the sense that you are\n> going to implement the input language we use (one thing I\n> personally care about while probably other people do not is the\n> conditional compilation \"ifdef::stalenotes[]\" in git.txt).\n> \n\nYes and no. I am not offering to clone *all* of AsciiDoc, just whatever \nsubset is necessary to format the git documentation. (Of course, having \nlooked at this very little so far, perhaps that really is all of \nAsciiDoc -- but it's certainly not all of xmlto.)\n\n> * You would need to duplicate the AsciiDoc 7 manual and\n> maintain it as well; otherwise, when later versions of\n> AsciiDoc comes, people who update our documentation will\n> refer to asciidoc website to learn the syntax, and find out\n> that your dialect does not match what is described there.\n> \n\nActually, I disagree with this. If we were to fork our own document \nformatter (or rather \"implement\" -- \"fork\" implies starting with the \nexisting code base) we would explicitly say its input was expected to be \nin the \"git documentation human-readable text format\" rather than \"git's \nimplementation of the AsciiDoc format.\" Then we could freely tweak \nwhatever parts of AsciiDoc we're not happy with, and precise \ncompatibility would be a total non-issue.\n\n> * How much can we really rely on your fork to be kept\n> maintained? When we need newer mark-up that is not offered\n> by AsciiDoc 7 clone, is it our plan to model that after\n> AsciiDoc X (X > 7), or we just come up with an extension of\n> our own?\n> \n\nMy thought would be to come up with our own syntax; that's a logical \nresult of me not considering this anything but \"a formatter whose input \nlooks suspiciously like AsciiDoc\".\n\nWhile I agree that that's extra work, it also seems to be the case that \n(a) git hasn't actually needed new markup very often, and (b) we've \nspent far more time dealing with AsciiDoc version-to-version \nincompatibilities than it would likely take to implement whatever new \nmarkup we needed.\n\n> * What would happen when xhtml11 goes out of fashion and we\n> would want to switch to newer formats?\n> \n\nIf I do this I'll try to structure the code in such a way that new \nformats could be added without huge pain. Will it be as flexible and \nconfigurable as xmlto? Absolutely not, which is kind of the point of the \nexercise. Adding a substantially different output format might require \nlogic changes to the formatter depending on the details, given that the \noptimization here will be for speed rather than extreme flexibility.\n\nOn the other hand, I don't think that's a short-term enough concern to \nbe worth worrying too much about; it'll be a long, long time before \nXHTML is completely replaced by anything else, just because of its \ngargantuan installed base of existing documents. And it's not like we \ncan't decide to switch to another formatter down the road if we want to. \n(Once we all have 64-core machines on our desktops, \"make -j64\" will \ncause AsciiDoc/xmlto to be sufficiently fast!)\n\n> * What to do with the user manual, which formats to docbook\n> \"book\" output?\n> \n\nAh, that's a sticking point, and an answer to my \"are there other output \nformats?\" question. I never pay attention to that file when I'm doing \nbuilds -- forgot it even existed. I'll ask one question first: is that \nDocbook output actually necessary, or would people be happy enough just \nhaving the user manual in XHTML?\n\nAssuming we really need a Docbook manual, it's tempting to say, \"keep \nusing AsciiDoc\" but then my assertion that we aren't really using \nAsciiDoc's input format kind of flies out the window. I wonder if it's \npossible to go from one of my proposed script's *output* formats to \nDocbook format -- is there software to take well-formed XHTML and turn \nit into that format? (Possibly that software is called \"xmlto\"...) I \nthink the transformation from .txt to .html is likely to be pretty \nlossless, so it should be theoretically possible, anyway.\n\n> It might be more worthwhile to research what other \"Text-ish\n> lightweight mark-up\" systems are availble, and if there is one\n> that is more efficient and can go to at least html and man,\n> one-time convert our documentation source to that format using\n> your Perl magic. The minimum requirements are:\n>\n> * The source is readable without too much mark-up distraction;\n>\n> * Can go to roff -man;\n>\n> * Can go to html.\n> \n\nI will look around and see what I can find. You're quite right, better \nto use already-existing code than reinvent the wheel.\n\n-Steve\n"},{"id":"49679","messageId":"1409.1186208258@bebe.enoyolf.org","threadId":"9373","inReplyTo":"46B418AA.4070701@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Doug Maxey","fromEmail":"dwm@enoyolf.org","sentAt":"2007-08-04T06:17:38Z","receivedAt":"2007-08-04T06:17:38Z","isPatch":false,"sender":{"key":"dwm@enoyolf.org","avatar":null},"body":"\nOn Sat, 04 Aug 2007 14:11:54 +0800, Steven Grimm wrote:\n> \n> I will look around and see what I can find. You're quite right, better \n> to use already-existing code than reinvent the wheel.\n\n/me dons his asbestos skivvies. \n\nWhat about perldoc? Thats about as minimal as it gets, yet can output \ntext or nroff quite nicely. Don't pay much attention to html myself.\n\n++doug\n"},{"id":"49680","messageId":"85wswbiwoz.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T07:30:04Z","receivedAt":"2007-08-04T07:30:04Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Junio C Hamano writes:\n\n> Steven Grimm writes:\n>\n>> Am I correct in observing that \"*roff -man\" and HTML are the only\n>> two output formats we care about, or do people use other formats in\n>> their private branches?\n>\n> I obviously do not speak for others, but the only format I care\n> about personally is the *.txt one. We picked asciidoc primarily\n> because the source language was readable.\n\n[...]\n\n> It might be more worthwhile to research what other \"Text-ish\n> lightweight mark-up\" systems are availble, and if there is one\n> that is more efficient and can go to at least html and man,\n> one-time convert our documentation source to that format using\n> your Perl magic. The minimum requirements are:\n>\n> * The source is readable without too much mark-up distraction;\n>\n> * Can go to roff -man;\n>\n> * Can go to html.\n\nNaturally I am biased, but Texinfo might be an option. The source is\neditable without too much distraction, one can generate HTML, printed\noutput, cross-referenced info files (those are really convenient for\nEmacs users), cross-referenced PDF output. For man pages, one could\nfollow the path outlined in\n.\nThat is probably the weakest point.\n\nPlain, user-readable ASCII text without any Texinfo markup can also be\ngenerated. One can even include images in info, PDF and HTML and have\nthose replaced by ASCII art in the plain text output.\n\nThere are some disadvantages: AFAIR, utf-8 characters will in general\nnot fly. One needs to code accented characters more or less\nexplicitly.\n\nTexinfo conversions are fast.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49688","messageId":"20070804091249.GA17821@uranus.ravnborg.org","threadId":"9373","inReplyTo":"46B418AA.4070701@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Sam Ravnborg","fromEmail":"sam@ravnborg.org","sentAt":"2007-08-04T09:12:49Z","receivedAt":"2007-08-04T09:12:49Z","isPatch":false,"sender":{"key":"sam@ravnborg.org","avatar":"https://gravatar.com/avatar/168a912606ed0742d840bb365e3cc21db390c36531a58341dc7a069cc1f15f62?d=mp&s=160"},"body":"On Sat, Aug 04, 2007 at 02:11:54PM +0800, Steven Grimm wrote:\n> Junio C Hamano wrote:\n> >If I read you correctly, what you are proposing to offer is a\n> >clone of asciidoc, perhaps AsciiDoc 7, with only xhtml11 and man\n> >backends. It is a subset in the sense that you will do only two\n> >backends, but otherwise is a clone in the sense that you are\n> >going to implement the input language we use (one thing I\n> >personally care about while probably other people do not is the\n> >conditional compilation \"ifdef::stalenotes[]\" in git.txt).\n> > \n> \n> Yes and no. I am not offering to clone *all* of AsciiDoc, just whatever \n> subset is necessary to format the git documentation. (Of course, having \n> looked at this very little so far, perhaps that really is all of \n> AsciiDoc -- but it's certainly not all of xmlto.)\n\nNever looked at Ascii-doc... but how about finding the loopholes\nin Ascii-doc to make it 10x faster?\nThat would benefit a larger user-base than just doing-it-ourself.\n\n\tSam\n"},{"id":"49692","messageId":"20070804133923.eb84a308.tihirvon@gmail.com","threadId":"9373","inReplyTo":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Timo Hirvonen","fromEmail":"tihirvon@gmail.com","sentAt":"2007-08-04T10:39:23Z","receivedAt":"2007-08-04T10:39:23Z","isPatch":false,"sender":{"key":"tihirvon@gmail.com","avatar":null},"body":"Junio C Hamano wrote:\n\n> It might be more worthwhile to research what other \"Text-ish\n> lightweight mark-up\" systems are availble, and if there is one\n> that is more efficient and can go to at least html and man,\n> one-time convert our documentation source to that format using\n> your Perl magic. The minimum requirements are:\n> \n> * The source is readable without too much mark-up distraction;\n> \n> * Can go to roff -man;\n> \n> * Can go to html.\n\nI used asciidoc too but it was really PITA to install and use so I wrote\na small tool (ttman) in C which converts .txt files directly to man\npages. It doesn't have html support but you could use man2html for that.\nUnfortunately it does not format as pretty html as asciidoc.\n\nhttp://onion.dynserv.net/git/?p=cmus.git;a=tree;f=Doc;h=8ab4e92a6356d9cca0d738130fe54026da8c690b;hb=54b6ddacd9d1387c256ce5e7d7d8bb3324799c04\n\nIt might be quite easy to extend ttman to output html too...\n\n-- \nhttp://onion.dynserv.net/~timo/\n"},{"id":"49693","messageId":"46B45B1E.5020104@midwinter.com","threadId":"9373","inReplyTo":"20070804091249.GA17821@uranus.ravnborg.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2007-08-04T10:55:26Z","receivedAt":"2007-08-04T10:55:26Z","isPatch":false,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"Sam Ravnborg wrote:\n> Never looked at Ascii-doc... but how about finding the loopholes\n> in Ascii-doc to make it 10x faster?\n> That would benefit a larger user-base than just doing-it-ourself.\n> \n\nBecause AsciiDoc is only half of the toolchain we use. (Though in your \ndefense, I made the mistake of only mentioning AsciiDoc by name, rather \nthan \"the AsciiDoc toolchain.\") We run asciidoc's output through xmlto, \nwhich is just as slow and is a highly general piece of software for \ndoing arbitrary transformations of XML documents. I won't say it's \nimpossible to speed up xmlto as well, of course, but it's probably an \norder of magnitude more work than implementing a new parser/renderer for \nour .txt files.\n\n-Steve\n"},{"id":"49698","messageId":"Pine.LNX.4.64.0708041235190.14781@racer.site","threadId":"9373","inReplyTo":"46B418AA.4070701@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-04T11:38:35Z","receivedAt":"2007-08-04T11:38:35Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 4 Aug 2007, Steven Grimm wrote:\n\n> Junio C Hamano wrote:\n>\n> > * How much can we really rely on your fork to be kept\n> > maintained? When we need newer mark-up that is not offered\n> > by AsciiDoc 7 clone, is it our plan to model that after\n> > AsciiDoc X (X > 7), or we just come up with an extension of\n> > our own?\n> > \n> \n> My thought would be to come up with our own syntax; that's a logical \n> result of me not considering this anything but \"a formatter whose input \n> looks suspiciously like AsciiDoc\".\n\nThere have been a few suggestions to step away from asciidoc in this \nthread now. IMNSVHO the only switch which would actually make sense, \nwould be towards the Wiki format.\n\nWhy?\n\nBecause right now, we have a _ton_ of documentation on the Gitwiki, and \nno easy way to import it back. We also have at least one document which \nis (semi-regularly) converted from ascii to Wiki markup.\n\nWiki markup is relatively easy to read (a bit more disruptive that \nasciidoc), but granted, it is lacking features such as the conditional \nthing Junio mentioned.\n\nCiao,\nDscho\n"},{"id":"49700","messageId":"Pine.LNX.4.64.0708041240500.14781@racer.site","threadId":"9373","inReplyTo":"20070804133923.eb84a308.tihirvon@gmail.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-04T11:46:59Z","receivedAt":"2007-08-04T11:46:59Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 4 Aug 2007, Timo Hirvonen wrote:\n\n> Junio C Hamano wrote:\n> \n> > It might be more worthwhile to research what other \"Text-ish\n> > lightweight mark-up\" systems are availble, and if there is one\n> > that is more efficient and can go to at least html and man,\n> > one-time convert our documentation source to that format using\n> > your Perl magic. The minimum requirements are:\n> > \n> > * The source is readable without too much mark-up distraction;\n> > \n> > * Can go to roff -man;\n> > \n> > * Can go to html.\n> \n> I used asciidoc too but it was really PITA to install and use\n\nI disagree. Whenever I had the need, installing asciidoc was pretty \nswift. No problems at all.\n\n> so I wrote a small tool (ttman) in C which converts .txt files directly \n> to man pages.\n\nI was impressed! Right until I saw that\n\n\t- it rolls its own parser/lexer without using bison/flex, which \n\t makes it much longer than necessary,\n\n\t- it looks like a perl script doing the same job would have been \n\t even smaller yet, and\n\n\t- the syntax is nowhere near asciidoc syntax.\n\nThe last point is really something to keep in mind. We have not only a \nlarge amount of documentation in that format, which would have to be \nconverted -- accurately! -- to the new format. We also have quite a \nnumber of documentation contributors which would have to be \"migrated\" \ntowards the new format.\n\nI think that Steven's goal is a laudable one. We have the 'man' and \n'html' branch mainly for the reason that some cannot/wantnot install \nasciidoc.\n\nBut I think that we do not have to have a _complete_ replacement. I, for \none, would be happy to see a small script which converts all the man pages \nmore or less accurately, with the main goal to be _fast_ and having as \nfew dependencies as possible (I think Perl is okay here).\n\nFor official releases, I'd still want to rely on asciidoc.\n\nCiao,\nDscho\n"},{"id":"49708","messageId":"85zm17h4pn.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"46B45B1E.5020104@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T12:19:48Z","receivedAt":"2007-08-04T12:19:48Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Steven Grimm writes:\n\n> Sam Ravnborg wrote:\n>> Never looked at Ascii-doc... but how about finding the loopholes\n>> in Ascii-doc to make it 10x faster?\n>> That would benefit a larger user-base than just doing-it-ourself.\n>> \n>\n> Because AsciiDoc is only half of the toolchain we use. (Though in your\n> defense, I made the mistake of only mentioning AsciiDoc by name,\n> rather than \"the AsciiDoc toolchain.\") We run asciidoc's output\n> through xmlto, which is just as slow and is a highly general piece of\n> software for doing arbitrary transformations of XML documents. I won't\n> say it's impossible to speed up xmlto as well, of course, but it's\n> probably an order of magnitude more work than implementing a new\n> parser/renderer for our .txt files.\n\nPersonally, I think it would make sense to move to a different\ndocumentation system, or at least a different organization. The\nproblem with the current layout is that it is basically flat.\n\nA system such as info, in contrast, is hierarchical, and organized\nwith indexes and cross references making it much easier to find\nthings. More importantly, it makes it possible to put things into\nperspective: which commands are porcelain, which are plumbing? What\ndo you do in a typical workflow? What are the related internal data\nstructures? Where are they documented? Can I print or navigate a\ncomplete PDF document explaining the whole system?\n\nThe manual pages of git have a high quality, but they remain manual\npages: they are all standalone, not putting the tool into a context or\nhierarchy. While the user manual is a place to start, it is more or\nless added as an afterthought: it does not structure the available\ndocumentation.\n\nFor Texinfo there is a large number of backends, and there are also\nusable reader plugins (Tkinfo, and the presumably embeddable GNOME\n\"yelp\" also displays info files and the embedded links, and of course\nthe wonderful Emacs info browser) for things like git-gui.\n\nIt may be that the asciidoc/Docbook workflow also contains ways to get\nsimilarly useful stuff out: comments welcome. I am just more\nacquainted with Texinfo myself.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49713","messageId":"20070804155129.a20cdb9b.tihirvon@gmail.com","threadId":"9373","inReplyTo":"Pine.LNX.4.64.0708041240500.14781@racer.site","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Timo Hirvonen","fromEmail":"tihirvon@gmail.com","sentAt":"2007-08-04T12:51:29Z","receivedAt":"2007-08-04T12:51:29Z","isPatch":false,"sender":{"key":"tihirvon@gmail.com","avatar":null},"body":"Johannes Schindelin wrote:\n\n> Hi,\n> \n> On Sat, 4 Aug 2007, Timo Hirvonen wrote:\n> \n> > I used asciidoc too but it was really PITA to install and use\n> \n> I disagree. Whenever I had the need, installing asciidoc was pretty \n> swift. No problems at all.\n\nWell asciidoc doesn't even have a Makefile. You have to copy the files\nmanually (maybe it's easier now, I don't know). Also getting it work\ncorrectly with xsl-stylesheets etc. was really frustrating experience.\nNow there's asciidoc, xmlto etc. in Arch Linux community repo but I\nwouldn't be surprised if it couldn't build the GIT documentation.\n\n> > so I wrote a small tool (ttman) in C which converts .txt files directly \n> > to man pages.\n> \n> I was impressed! Right until I saw that\n> \n> \t- it rolls its own parser/lexer without using bison/flex, which \n> \t makes it much longer than necessary,\n\nI've never liked parser generators.\n\n> \t- it looks like a perl script doing the same job would have been \n> \t even smaller yet, and\n\nVery likely but perl is incompatible with my brain :)\n\n> \t- the syntax is nowhere near asciidoc syntax.\n\nI needed something really simple. asciidoc's syntax is full of\nsurprises and it's much harder to parse.\n\nOf course having a perl script which could convert asciidoc files\ndirectly to man and html would be really nice. We just need some brave\nperl hacker to write the script.\n\n> For official releases, I'd still want to rely on asciidoc.\n\nAgreed, rushing to change the documentation format wouldn't be wise.\n\n-- \nhttp://onion.dynserv.net/~timo/\n"},{"id":"49715","messageId":"200708041511.05191.robin.rosenberg.lists@dewire.com","threadId":"9373","inReplyTo":"7vzm18jg7p.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Robin Rosenberg","fromEmail":"robin.rosenberg.lists@dewire.com","sentAt":"2007-08-04T13:11:04Z","receivedAt":"2007-08-04T13:11:04Z","isPatch":false,"sender":{"key":"robin.rosenberg@dewire.com","avatar":"https://avatars.githubusercontent.com/u/46357?v=4"},"body":"\nCommit 281a53bb79786a6d7e54f9715cc8ad46fc2bdb0e introduced some stains on my man pages. They\nlook like:\n\n .ft C\n A---B---C topic\n /\n D---E---F---G master\n .ft\n\nVersions (Mandriva 20071):\n\n\tasciidoc-8.1.0-1mdv2007.1\n\tdocbook-style-xsl-1.72.0-1mdv2007.1\n\n\nYou should also mention that the man pages goes to a new location when installed.\n\n-- robin\n"},{"id":"49716","messageId":"200708041626.36419.ismail@pardus.org.tr","threadId":"9373","inReplyTo":"7vodhoj8l2.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Ismail Dönmez","fromEmail":"ismail@pardus.org.tr","sentAt":"2007-08-04T13:26:36Z","receivedAt":"2007-08-04T13:26:36Z","isPatch":false,"sender":{"key":"ismail@pardus.org.tr","avatar":null},"body":"On Saturday 04 August 2007 06:13:13 you wrote:\n> Ismail Dönmez writes:\n> > Attached patch from Fedora against docbook-xsl 1.73 fixes the issue.\n>\n> Thanks. I'll mention this in the INSTALL document somewhere.\n>\n> Perhaps the patch should go to docbook-xsl maintainers.\n\nI sent a mail to docbook mailing list.\n\nRegards,\nismail\n\n-- \nPerfect is the enemy of good\n"},{"id":"49719","messageId":"Pine.LNX.4.64.0708041432350.7932@beast.quantumfyre.co.uk","threadId":"9373","inReplyTo":"200708041511.05191.robin.rosenberg.lists@dewire.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Julian Phillips","fromEmail":"julian@quantumfyre.co.uk","sentAt":"2007-08-04T13:42:18Z","receivedAt":"2007-08-04T13:42:18Z","isPatch":false,"sender":{"key":"julian@quantumfyre.co.uk","avatar":"https://avatars.githubusercontent.com/u/948888?v=4"},"body":"On Sat, 4 Aug 2007, Robin Rosenberg wrote:\n\n>\n> Commit 281a53bb79786a6d7e54f9715cc8ad46fc2bdb0e introduced some stains on my man pages. They\n> look like:\n>\n> .ft C\n> A---B---C topic\n> /\n> D---E---F---G master\n> .ft\n>\n> Versions (Mandriva 20071):\n>\n> \tasciidoc-8.1.0-1mdv2007.1\n> \tdocbook-style-xsl-1.72.0-1mdv2007.1\n\ndocbook xsl 1.72 is the culprit. This version has extra escaping rules \nthat weren't in 1.71 and were removed for 1.73. In addition these rules \nare not backwardly compatible. Basically, you can't build the git docs \nproperly with 1.72 ...\n\nSee http://thread.gmane.org/gmane.comp.version-control.git/52369\n\n-- \nJulian\n\n ---\n you should always know where your inodes are, and who they are with\n"},{"id":"49729","messageId":"20070804142948.GB10294@fieldses.org","threadId":"9373","inReplyTo":"Pine.LNX.4.64.0708041235190.14781@racer.site","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-04T14:29:48Z","receivedAt":"2007-08-04T14:29:48Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Aug 04, 2007 at 12:38:35PM +0100, Johannes Schindelin wrote:\n> There have been a few suggestions to step away from asciidoc in this \n> thread now. IMNSVHO the only switch which would actually make sense, \n> would be towards the Wiki format.\n> \n> Why?\n> \n> Because right now, we have a _ton_ of documentation on the Gitwiki, and \n> no easy way to import it back. We also have at least one document which \n> is (semi-regularly) converted from ascii to Wiki markup.\n\nPossibly I'm paranoid, but for the stuff we distribute in our source\ntree I'd like to know who contributed, and to know that they were really\naware of the license. That may be an obstacle to mass import of\ndocumentation from the wiki--I don't know.\n\nWhether the wiki markup is a sensible markup language is a separate\nquestion.\n\n--b.\n"},{"id":"49736","messageId":"200708041719.52682.barra_cuda@katamail.com","threadId":"9373","inReplyTo":"7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Michael","fromEmail":"barra_cuda@katamail.com","sentAt":"2007-08-04T15:19:52Z","receivedAt":"2007-08-04T15:19:52Z","isPatch":false,"sender":{"key":"barra_cuda@katamail.com","avatar":"https://avatars.githubusercontent.com/u/16371673?v=4"},"body":"On Saturday 04 August 2007 06:38, Junio C Hamano wrote:\n> It might be more worthwhile to research what other \"Text-ish\n> lightweight mark-up\" systems are availble, and if there is one\n> that is more efficient and can go to at least html and man,\n> one-time convert our documentation source to that format using\n> your Perl magic.  The minimum requirements are:\n> \n>  * The source is readable without too much mark-up distraction;\n> \n>  * Can go to roff -man;\n> \n>  * Can go to html.\n\nI know about txt2tags, but I'm not sure it will be the right choice.\n\nhttp://txt2tags.sourceforge.net/\n\nIt's in python, uses a markup similar to wiki, and can be used to\ncreate documentation in man, html, plain txt.\n\nBut I haven't used it very much.\n"},{"id":"49743","messageId":"46B4A35E.5040601@midwinter.com","threadId":"9373","inReplyTo":"85zm17h4pn.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Steven Grimm","fromEmail":"koreth@midwinter.com","sentAt":"2007-08-04T16:03:42Z","receivedAt":"2007-08-04T16:03:42Z","isPatch":false,"sender":{"key":"koreth@midwinter.com","avatar":"https://gravatar.com/avatar/71b4d2e8b62f168bdc9e9205341159e3567003b4f9e2127c617c5fa0a1f5bad2?d=mp&s=160"},"body":"David Kastrup wrote:\n> A system such as info, in contrast, is hierarchical, and organized\n> with indexes and cross references making it much easier to find\n> things.\n\nReally? I find info a huge pain in the butt most of the time. I can't \njust do a simple text search for the information I want in the relevant \nmanpage; I have to go navigating around to the appropriate subsection \n(and that's assuming I know where it is) and am forced to use the \nemacs-style pager whether I like it or not (not a big emacs fan here). \nIt always ticks me off when I go to read the manpage for some command \nand it tells me to go read the info page if I want complete documentation.\n\nI would definitely not want to move to a documentation system that \nprevented me from typing \"man git-commit\" to get a list of all the \ncommand line options for that command.\n\nHowever, that said, I have no objection to an alternate view of the same \ninformation that's organized differently.\n\nAm I alone in my dislike of info, I wonder?\n\n-Steve\n"},{"id":"49747","messageId":"Pine.LNX.4.64.0708041706200.14781@racer.site","threadId":"9373","inReplyTo":"46B4A35E.5040601@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-04T16:08:48Z","receivedAt":"2007-08-04T16:08:48Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 5 Aug 2007, Steven Grimm wrote:\n\n> David Kastrup wrote:\n> > A system such as info, in contrast, is hierarchical, and organized\n> > with indexes and cross references making it much easier to find\n> > things.\n> \n> Really? I find info a huge pain in the butt most of the time. I can't just do\n> a simple text search for the information I want in the relevant manpage;\n\nI see the same.\n\n> Am I alone in my dislike of info, I wonder?\n\nThere are so many reasons not to switch to info, but what you illustrated \nis a very good one of those.\n\nBut yes, if you have the time, and it would be fun for you (before your \nbattery runs flat), I'd appreciate a small script to do a \nquick-and-not-so-dirty conversion. Heck, if you use some kind of object \norientation, I might be talked into providing the html backend.\n\nCiao,\nDscho\n"},{"id":"49751","messageId":"857iobfenn.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"46B4A35E.5040601@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T16:27:56Z","receivedAt":"2007-08-04T16:27:56Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Steven Grimm writes:\n\n> David Kastrup wrote:\n>> A system such as info, in contrast, is hierarchical, and organized\n>> with indexes and cross references making it much easier to find\n>> things.\n>\n> Really? I find info a huge pain in the butt most of the time.\n> I can't just do a simple text search for the information I want in\n> the relevant manpage; I have to go navigating around to the\n> appropriate subsection (and that's assuming I know where it is)\n\nYou are presumably talking about the standalone reader. I never use\nit, so can't really say much about it. With Emacs, you just do C-s\nand search. Hitting C-s again will extend the search to the section,\nand then to the whole file.\n\n> and am forced to use the emacs-style pager whether I like it or not\n> (not a big emacs fan here). It always ticks me off when I go to read\n> the manpage for some command and it tells me to go read the info\n> page if I want complete documentation.\n>\n> I would definitely not want to move to a documentation system that\n> prevented me from typing \"man git-commit\" to get a list of all the\n> command line options for that command.\n\nNobody said that we would want to get rid of man pages.\n\nAnyway, with the info reader, you should at worst use something like\ninfo git\ni git-commit RET\nto get to the git-commit man page equivalent.\n\n> However, that said, I have no objection to an alternate view of the\n> same information that's organized differently.\n>\n> Am I alone in my dislike of info, I wonder?\n\nI don't use the standalone info reader. It is likely quite less\nsophisticated and convenient than what Emacs does with info files.\nThe few times I have used it, I felt inconvenienced IIRC, though it\nhas supposedly been improved some time ago after being left in the\nlurch for quite long. But actually you can also use yelp to browse\ninfo pages (point it at, say, info:coreutils).\n\nSo I would definitely agree with your assessment that _replacing_ the\nman pages by info would not be the right way to go. However, nobody\nasked for that. The idea was to use _Texinfo_, and this produces\nplain text, HTML, info files, quite nice PDF and some other formats.\nOf _course_, we want to have man pages as well. I pointed out a\nreference to the GCC project where they explain how they generate man\npages from Texinfo. One would have to check whether this can be\napplied to the git pages, of course.\n\nThere was also the question how to integrate documentation into\nsomething like gitk, and there is a Tkinfo widget that could\nconceivably be used. Texinfo files can also be converted into flat\ntext files with basic markup (and man pages don't give you more than\nthat, anyway).\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49756","messageId":"alpine.LFD.0.999.0708040954320.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85zm17h4pn.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-04T16:59:08Z","receivedAt":"2007-08-04T16:59:08Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 4 Aug 2007, David Kastrup wrote:\n> \n> A system such as info, in contrast, is hierarchical, and organized\n> with indexes and cross references making it much easier to find\n> things.\n\nYou must be kidding. Texinfo is the worst documentation format EVER. And \nthe readers universally suck too, unless you're a total GNU emacs fan and \nhave been for a decade, and have problems understanding people who don't \nlike the all-in-one mentality.\n\nThere are absolutely _zero_ advantages in Texinfo over AsciiDoc. It has \nall the same disadvantages, except the source files are *also* unreadable \n(which is the one really nice feature of AsciiDoc - you can ignore \neverything else, and just read the original .txt file).\n\n\t\t\tLinus\n"},{"id":"49760","messageId":"85myx7dwb3.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708040954320.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T17:49:36Z","receivedAt":"2007-08-04T17:49:36Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Linus Torvalds writes:\n\n> On Sat, 4 Aug 2007, David Kastrup wrote:\n>> \n>> A system such as info, in contrast, is hierarchical, and organized\n>> with indexes and cross references making it much easier to find\n>> things.\n>\n> You must be kidding. Texinfo is the worst documentation format EVER.\n\nOh come on. It was the first hyperlinked and hierarchical format\nbefore HTML even existed. Its age shows, but the replacements have\nnot managed to produce anything more useful. There have been\ndiscussions about replacing the _info_ format with an HTML or XHTML\nsubset, however, that conveys the same amount of hierarchical\ninformation.\n\n> And the readers universally suck too, unless you're a total GNU\n> emacs fan and have been for a decade, and have problems\n> understanding people who don't like the all-in-one mentality.\n\nActually, a decade ago the Emacs-internal info reader was worse than\nit is now.\n\nAny, after you have in your usual amicable manner declared anybody\ninsane that would not use the same tools as you, let us come back to\nthe plain facts again.\n\n> There are absolutely _zero_ advantages in Texinfo over AsciiDoc.\n\nThere are, of course, advantages to Texinfo. Any system that is not\ncompletely braindead has some unique advantages, and not everything\nnot designed by you is braindead.\n\nOne advantage to Texinfo is that it is _structured_: whether or not\nyou like the available info readers, there is the information \"up\",\n\"next\", \"previous\" in every node, and every node has a hyperlinkable\nname which you can use for referring to it. And the info readers are\naware of that, and you can navigate using single keystrokes.\n\nNow it may well be possible to put the same information into AsciiDoc\nfiles, but there are no _readers_, bad or not, that would make use of\nit.\n\nI can specify something like\n\n(info \"(gcc) Extended Asm\")\n\nand when you are reading mail in Emacs, you can click on that line and\nget to the respective page in a manual comprising hundreds of pages.\nYou can, of course, also type\ninfo \"(gcc) Extended Asm\"\ninto your command line and use the standalone info reader to get\nimmediately to that line.\n\nYou can also get there by typing\n\ninfo gcc\ni assem \nand picking the right of three choices from the index. The standalone\nreader may not be pretty, but it does the job of accessing those\ninformations, and you can with single keypresses go up and forward in\na hierarchically organized, _structured_ manual of hundreds of pages.\n\nAnd as opposed to AsciiDoc, there _are_ readers that make use of this\ninformation.\n\n> It has all the same disadvantages, except the source files are\n> *also* unreadable (which is the one really nice feature of AsciiDoc\n> - you can ignore everything else, and just read the original .txt\n> file).\n\nSo what?\n\n makeinfo --plaintext\n\nexists. The important thing for a source file format is that it is\n_writeable_. Restricting a source file format to carry just that kind\nof information which can be made to look pretty is a mistake in my\nbook.\n\nAnyway, here are some sections from AUCTeX's README generated from\nreadme.texi:\n\n Introduction to AUCTeX\n **********************\n\n This file gives a brief overview of what AUCTeX is. It is *not* an\n attempt to document AUCTeX. Real documentation for AUCTeX is available\n in the manual, which should be available as an info file after\n installation.\n\n 1 Installation\n **************\n\n Read the `INSTALL' or `INSTALL.windows' file respectively for\n comprehensive information about how to install AUCTeX.\n\n The installation routine tries to make the modes provided by AUCTeX\n the default for all supported file types. If this does not happen in\n your case, add\n (load \"auctex.el\" nil t t)\n to your init file and consult the section about loading the package\n in the `INSTALL' file.\n\n If you want to change the modes for which it is operative instead of\n the default, use\n M-x customize-variable RET TeX-modes RET\n\n If you want to remove a preinstalled AUCTeX completely before any of\n its modes have been used,\n (unload-feature 'tex-site)\n should accomplish that.\n\n If you are considering upgrading AUCTeX, the recent changes are\n described in the `CHANGES' file.\n\nActually, the indentation could be prettier if the quote environments\nwere properly set off as paragraphs.\n\nAnyway, here is the corresponding source (it suffers from the\ncomplications that it is the start of the file, and that the README\ncan be produced both as a top-level standalone file, as well as a\nsubordinate chapter in the containing complete documentation).\n\n @include macros.texi\n @ifset rawfile\n @chapheading Introduction to @AUCTeX{}\n @raisesections\n @end ifset\n\n @ifclear rawfile\n @node Introduction, Installation, Copying, top\n @chapter Introduction to @AUCTeX{}\n @end ifclear\n\n @ifset rawfile\n This file\n @end ifset\n @ifclear rawfile\n This section of the @AUCTeX{} manual\n @end ifclear\n gives a brief overview of what @AUCTeX{} is. It is @strong{not} an\n attempt to document @AUCTeX{}. Real documentation for @AUCTeX{} is\n available in the\n @ifset rawfile\n manual, which should be available as an info file after installation.\n @end ifset\n @ifclear rawfile\n rest of the manual.\n @end ifclear\n\n @section Installation\n\n Read the\n @ifset rawfile\n @file{INSTALL} or @file{INSTALL.windows} file\n @end ifset\n @ifclear rawfile\n section @ref{Installation}, or @ref{Installation under MS Windows},\n @end ifclear\n respectively for comprehensive information about how to install\n @AUCTeX{}.\n\n The installation routine tries to make the modes provided by @AUCTeX{}\n the default for all supported file types. If this does not happen in\n your case, add\n @lisp\n (load \"auctex.el\" nil t t)\n @end lisp\n to your init file and consult the section\n @ifset rawfile\n about loading the package in the @file{INSTALL} file.\n @end ifset\n @ifclear rawfile\n @ref{Loading the package}.\n @end ifclear\n\n If you want to change the modes for which it is operative instead of the\n default, use\n @example\n @kbd{M-x customize-variable RET TeX-modes RET}\n @end example\n\n If you want to remove a preinstalled @AUCTeX{} completely before any of\n its modes have been used,\n @example\n (unload-feature 'tex-site)\n @end example\n should accomplish that.\n\n If you are considering upgrading @AUCTeX{}, the recent changes are\n described in\n @ifset rawfile\n the @file{CHANGES} file.\n @end ifset\n @ifclear rawfile\n @ref{Changes}.\n @end ifclear\n\n\nThis is reasonable writeable, and it contains all the information for\nhyperlinking and cross-referencing the stuff. It is not necessarily\noverly pretty, but it can be converted very efficiently both into\nsingle file PDF which can be either navigated on its own or printed,\nor into raw text files similar to the existing documentation, or into\nHTML or into info, for which efficient _hierarchical_ readers exist.\n\nNow XML certainly has all the expressivity needed to represent the\nsame information, but you still need a reader that actually makes use\nof it. And you have to have the information also expressed in\nAsciiDoc, and the requirement that it still looks good in the _source_\ncode makes it awkward designing an appropriate ASCII way of\nrepresenting the information.\n\nAsciiDoc may have the _potential_ to do the same, but at the current\npoint of time, I don't see that there are tools for conveniently\nnavigating hundred-page and longer AsciiDoc documents. And there are\nfor Texinfo.\n\nI am fine if you don't like Texinfo and would rather use something\ndifferent with the _same_ amount of information content as Texinfo\nhas, and with readers that make use of it. Heck, _if_ the source\nformat can be made to represent the same information, it might be\npossible to create Texinfo or at least info pages from it.\n\nTexinfo is not really the point. It is just there to show that it\n_is_ possible to work with documentation that provides a _structured_\nview into a _large_, coherent document. Of course, by far the best\nreader for it (or rather the generated info files) is Emacs, and\nthat's definitely a drawback for those who don't work with it. The\nstandalone reader has been sub-par for decades. At the current point\nof time, it may be considered tolerable, but not exciting. But at\nleast it exists.\n\nMan pages don't scale to hundreds of pages, and neither does the\ncurrent organization of git documentation do this. If you can propose\nsomething that works at least as well as Texinfo for navigating\nhundreds of pages of information, go ahead.\n\nIt is not that Texinfo is great. It is just that I don't see an\nalternative that sucks less right now. Lots of _formats_ would have\npotential for it, but the readers for making use of such documentation\nare just not there. And PDF is not really a good alternative, since\nfonts, pagination and linear order are not optimized for screen, but\nfor print. And of course, it is much slower to display, and has no\nup/down navigation, but only forward/back.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49769","messageId":"alpine.LFD.0.999.0708041156550.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85myx7dwb3.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-04T19:03:08Z","receivedAt":"2007-08-04T19:03:08Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 4 Aug 2007, David Kastrup wrote:\n> >\n> > You must be kidding. Texinfo is the worst documentation format EVER.\n> \n> Oh come on. It was the first hyperlinked and hierarchical format\n> before HTML even existed.\n\nYes. And it should have died after html took its place.\n\n> Actually, a decade ago the Emacs-internal info reader was worse than\n> it is now.\n\nWow. I've used the emacs one, and the stand-alone info one, and both are \npretty horrid. You're saying that they used to be _worse_?\n\n(Admittedly, my GNU emacs-fu is very weak. I use an emacs-like editor, but \nit's just an editor, and it's subtly different, so I actually find the \n\"real\" emacs to be really disturbing on so many levels ;)\n\n> [ structure ]\n>\n> And as opposed to AsciiDoc, there _are_ readers that make use of this\n> information.\n\nNone that any normal user would want to use. \n\nThe thing is, html does a much better job of all of that, simply because \nthere are useful readers. The same, btw, goes for man-pages: even though \nthey have no structure at all, just the fact that normal people know how \nto use them, they are actually superior to info pages!\n\nThat's something that the FSF seems to have missed in their push for info \nformat: a lot of FSF programs have really substandard man-pages, but that \ndoesn't mean that people read the info ones _anyway_. Because the readers \nare so disgustingly horrible, plain man-pages are actually much more \nuseful, despite the fact that they don't have any cross-referencing etc.\n\n\t\tLinus\n"},{"id":"49771","messageId":"85bqdndqgr.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708041156550.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-04T19:55:48Z","receivedAt":"2007-08-04T19:55:48Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Linus Torvalds writes:\n\n> On Sat, 4 Aug 2007, David Kastrup wrote:\n>> >\n>> > You must be kidding. Texinfo is the worst documentation format EVER.\n>> \n>> Oh come on. It was the first hyperlinked and hierarchical format\n>> before HTML even existed.\n>\n> Yes. And it should have died after html took its place.\n\nThe problem is that html, not even now, offers useful standardized\nstructural navigation information, so no reader can offer keypresses\nto follow the non-existing information. I'd really like HTML to have\ntaken its place. However, in spite of all the bloat of HTML\nprocessors (firefox takes more memory than Emacs, and Emacs is my\nbloody _desktop_), and in spite of it being orders of magnitude\nslower, it does not offer this navigation. It offers no cross-page\nsearch facilities.\n\nYou can't navigate through the structure of the equivalent of hundreds\nof printed pages in an HTML browser. Not by navigating, not by plain\ntext searching.\n\nI'll be all set to bury Texinfo once HTML has taken its place.\nUnfortunately, it has taken a different place up to now.\n\n>> Actually, a decade ago the Emacs-internal info reader was worse\n>> than it is now.\n>\n> Wow. I've used the emacs one, and the stand-alone info one, and both\n> are pretty horrid. You're saying that they used to be _worse_?\n\nThe standalone reader was rather horrid a few years ago: it used not\nto know the normal page and cursor commands and beeped at quite a few\nthings. It is quite better now. Bit it is not Emacs.\n\n> (Admittedly, my GNU emacs-fu is very weak. I use an emacs-like\n> editor, but it's just an editor, and it's subtly different, so I\n> actually find the \"real\" emacs to be really disturbing on so many\n> levels ;)\n>\n>> [ structure ]\n>>\n>> And as opposed to AsciiDoc, there _are_ readers that make use of\n>> this information.\n>\n> None that any normal user would want to use.\n\nLinus, do you really think that the editor _you_ use is used by more\npeople than Emacs? Think again.\n\nAnyway, Emacs might, for all your polemics are worth, be an editor\nthat a \"normal user\" would not want to use: it has a tough learning\ncurve. It has considerably flattened in recent years, and\nparticularly Emacs 22 is a big step forward, but no sane person would\nuse Emacs if there was anything else that sucked less.\n\nThere isn't. And in spite of all your denial, there isn't for\nTexinfo, either. You can't do a plain text search through hundreds of\nHTML pages. You need a single page for that, and then navigation,\nalready bad in HTML, becomes absolutely horrid.\n\nYour best bet nowadays might be a PDF reader with plain text search in\nthe document intended for printing. Something which has a page layout\nand fonts not suited for screen reading.\n\nYou can't usefully find your way through a hundreds-pages manual page.\n\n> The thing is, html does a much better job of all of that, simply\n> because there are useful readers.\n\nBut there aren't. Not for documents of several hundred pages. Not\nuntil you download all of them and then do a grep on the flat files\nwhen you are looking for some keyword anywhere in the whole bunch.\n\nThat is an amount of suckage that neither Emacs nor the info reader\ncould ever hope to replicate.\n\n> The same, btw, goes for man-pages: even though they have no\n> structure at all, just the fact that normal people know how to use\n> them, they are actually superior to info pages!\n\nFor single pages, yes. For hundreds of pages, this falls apart. Man\npages don't scale.\n\n> That's something that the FSF seems to have missed in their push for\n> info format: a lot of FSF programs have really substandard\n> man-pages, but that doesn't mean that people read the info ones\n> _anyway_. Because the readers are so disgustingly horrible, plain\n> man-pages are actually much more useful, despite the fact that they\n> don't have any cross-referencing etc.\n\nAgain, you presume to know the rest of the world, and the rest of the\nworld is \"normal\" and just like you.\n\nI will readily agree with you that for the longest time, reading info\nfiles outside of Emacs was painful enough to make it mostly useless.\nWith the current standalone info reader, it is merely annoying.\n\nAnd inside of Emacs (and using Emacs is not as much the equivalent of\ndoing appendectomy on yourself with a fork because there is no\n_equivalent_ to do the same job, but has progressed to a reasonably\nsharp knife), info has moved from \"tolerable\" to \"quite usable\" under\nEmacs 22: you can easily search whole documents, single nodes,\nchapters. Pretty much everything is clickable by mouse (with mouse\nbutton 1), including the structural information that _stays_ on top of\nyour window.\n\nAnyway, like it or not, the current form of git documentation is not\nstructured, and that means that it is very hard to get the big\npicture. Texinfo might have readers that suck, but other formats\ndon't have readers doing the job at all when we are talking about\nfinding your way in a document of some hundred pages. PDF at the\ncurrent point of time is about the closest you can come, and it is\nprint-oriented and slow. And it certainly does not offer something\nlike typing\ni assembl RET\nin order to jump through the index at the first page referring to\nassembly language.\n\nLike with TeX itself, the scandal is not that decade-old technology is\nstill in use, but rather that nobody has replaced it with anything\nactually doing the same job, in spite of all the information being\nfreely available and in spite of the old technology being really\narcane.\n\nFind me an HTML reader that allows keypress-based structured\nnavigation through documents of a few hundred pages, and _then_ talk\nabout Texinfo being supplanted.\n\nHeck, _nobody_ likes Texinfo, including myself. It is a stupid format\nand not remarkably fun to write or understand. It is just that there\nare no bloody tools doing the same job. After all these years, and in\nspite of a really terrible standalone reader for the longest time.\n\nI can perfectly well understand your lack of enthusiasm. And feel\nfree to call me and the FSF and info and who- and whatever else any\nname you like (you won't be able to refrain anyhow). But the fact\nremains that the best way to find some information in the current git\ndocumentation is not using HTML. It is not using man, unless you\nalready know what you are looking for.\n\nNo, currently the _only_ viable search interface into git's\ndocumentation as a whole consists of grep and less.\n\nAnd for your favorite \"normal user\" scapegoat, that sucks even worse\nthan the standalone info reader, let alone Emacs.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49779","messageId":"20070804212704.GA10971@fieldses.org","threadId":"9373","inReplyTo":"85bqdndqgr.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-04T21:27:04Z","receivedAt":"2007-08-04T21:27:04Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sat, Aug 04, 2007 at 09:55:48PM +0200, David Kastrup wrote:\n> The problem is that html, not even now, offers useful standardized\n> structural navigation information,\n\nActually html is able to represent that kind of information, though\nbrowsers don't seem to take advantage of it. E.g. install something\nlike this firefox extension:\n\n\thttp://www.christophm.de/software/firefox/cmSiteNavigation/\n\nand then look at\n\n\thttp://www.gnu.org/software/libc/manual/html_node/index.html\n\nDoesn't seem to have keyboard shortcuts, but it's mildly useful.\n\n--b.\n"},{"id":"49812","messageId":"alpine.LFD.0.999.0708042127160.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85bqdndqgr.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-05T04:29:26Z","receivedAt":"2007-08-05T04:29:26Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 4 Aug 2007, David Kastrup wrote:\n> >\n> > None that any normal user would want to use.\n> \n> Linus, do you really think that the editor _you_ use is used by more\n> people than Emacs? Think again.\n\nNo.\n\nBut I'm also not confused enough to think that people should use \nmicro-emacs for reading man-pages.\n\nThe UNIX philosophy is \"do one thing, and do it well\". \n\nMan-pages with man. html with a web browser. And edit stuff with an \neditor.\n\nWhy the *hell* do you confuse my choice of editor with my choice of \nman-page format? I didn't. \n\nThat whole \"do everything in emacs\" is a disease. And then emacs users \nthink that it's \"sane\".\n\n\t\tLinus\n"},{"id":"49835","messageId":"85bqdmctcl.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708042127160.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T07:51:06Z","receivedAt":"2007-08-05T07:51:06Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Linus Torvalds writes:\n\n> On Sat, 4 Aug 2007, David Kastrup wrote:\n>> >\n>> > None that any normal user would want to use.\n>> \n>> Linus, do you really think that the editor _you_ use is used by more\n>> people than Emacs? Think again.\n>\n> No.\n>\n> But I'm also not confused enough to think that people should use \n> micro-emacs for reading man-pages.\n\nCould you refrain from using name-calling on everybody that does not\nshare your preferences? It is annoying to hear you talk all the time\nabout \"normal\", \"sane\", \"confused\" and so on.\n\n> The UNIX philosophy is \"do one thing, and do it well\".\n\nAnd Emacs does text, and does it well. It is just that very much\ninformation can ultimately be viewed as text. For example, I can run\ngrep or locate inside of Emacs. Nothing exciting. And then I can\nclick on the lines those put out, and get moved to the corresponding\nline in the source code, in my editor. Again, nothing exciting, but\nit does not work with disconnected tools without the glue Emacs\nprovides. There are other IDEs providing that sort of thing, but\nusually they work just with output they produced themselves.\n\nUsing Emacs to read man-pages means that I can grab manpage content\neasily with my accustomed editing commands and paste them into a mail\nI am composing. Without having to use a mouse or GUI.\n\nIt enables workflows that are not possible outside of it. It is ok if\nyou don't find the tradeoff appealing, but that does not make you\n\"normal\" and other people \"confused\" and \"insane\".\n\nSo please get a grip and focus on what we were actually talking\nabout. Not Emacs, but rather documentation formats.\n\n> Man-pages with man.\n\nActually, Emacs \"woman\" does a pretty good job with those, offers\nconvenient man page name completion and works on Windows and similar\nplatforms without needing\n\n> html with a web browser. And edit stuff with an editor.\n>\n> Why the *hell* do you confuse my choice of editor with my choice of\n> man-page format? I didn't.\n\nWhy the hell do you keep changing the topic and go off on sideline\nrants.\n\n> That whole \"do everything in emacs\" is a disease. And then emacs\n> users think that it's \"sane\".\n\nFocus. How do you propose to manage documention of a hundred pages an\nmore conveniently, finding information easily by text, index,\nhyperlinks? A single large HTML page? A documentation directory full\nof *.txt files which you can grep through (not that Emacs would not be\nuseful for that, too)?\n\nHow do you find all information pertaining to \"remote tracking\nbranches\" in the git documentation? Explain your workflow with that,\nand explain why a sane person would prefer that over typing\ninfo git\ni remote TAB RET , , ,\nand being taken to the respective text locations in turn.\n\nStandalone info _is_ a single application doing a single job:\nnavigating large hyperlinked plain text documentation efficiently. It\nmay be an _ugly_ application, but instead of saying what you use\ninstead in your daily workflow, you revert to name-calling.\n\nIf you have a _working_ solution to offer for that task, try\npresenting it instead of calling people using other tools names.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49848","messageId":"20070805094247.GE12507@coredump.intra.peff.net","threadId":"9373","inReplyTo":"85myx7dwb3.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-08-05T09:42:47Z","receivedAt":"2007-08-05T09:42:47Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Aug 04, 2007 at 07:49:36PM +0200, David Kastrup wrote:\n\n> I can specify something like\n> \n> (info \"(gcc) Extended Asm\")\n> \n> and when you are reading mail in Emacs, you can click on that line and\n> get to the respective page in a manual comprising hundreds of pages.\n\nUgh. A documentation referencing system that works only in one\nparticular editor, or with one particular documentation format?\n\nPlease, the net decided on a standard for referencing resources long\nago, and they are called URLs.\n\n-Peff\n"},{"id":"49851","messageId":"20070805095052.GF12507@coredump.intra.peff.net","threadId":"9373","inReplyTo":"46B4A35E.5040601@midwinter.com","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-08-05T09:50:52Z","receivedAt":"2007-08-05T09:50:52Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Aug 05, 2007 at 12:03:42AM +0800, Steven Grimm wrote:\n\n> Really? I find info a huge pain in the butt most of the time. I can't\n> just do a simple text search for the information I want in the\n> relevant manpage; I have to go navigating around to the appropriate\n> subsection (and that's assuming I know where it is) and am forced to\n> use the emacs-style pager whether I like it or not (not a big emacs\n> fan here). It always ticks me off when I go to read the manpage for\n> some command and it tells me to go read the info page if I want\n> complete documentation.\n\nI also find 'info' pages very painful to read. However, if you haven't\ntried it, the \"pinfo\" viewer gives a much friendlier (IMHO) interface.\nIt's more or less based on the lynx interface.\n\n http://pinfo.alioth.debian.org/\n\n-Peff\n"},{"id":"49852","messageId":"85abt6b91w.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"20070805094247.GE12507@coredump.intra.peff.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T09:54:51Z","receivedAt":"2007-08-05T09:54:51Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Jeff King writes:\n\n> On Sat, Aug 04, 2007 at 07:49:36PM +0200, David Kastrup wrote:\n>\n>> I can specify something like\n>> \n>> (info \"(gcc) Extended Asm\")\n>> \n>> and when you are reading mail in Emacs, you can click on that line\n>> and get to the respective page in a manual comprising hundreds of\n>> pages.\n>\n> Ugh. A documentation referencing system that works only in one\n> particular editor,\n\nThat works in readers of the info format. Do HTML references work\noutside of HTML readers?\n\n> or with one particular documentation format?\n>\n> Please, the net decided on a standard for referencing resources long\n> ago, and they are called URLs.\n\nThe last time I looked, URLs were not a common way to implement\nbookmarks except in HTML, namely \"with one particular documentation\nformat\".\n\nAnd you don't need an HTML reader to use those \"resources\" in HTML?\nGet real.\n\nAnyway, the referencing in _Texinfo_ gets translated into info\nreferences in info formats, URL bookmarks in HTML, PDF links in PDF\nand a textual description (since you can't let a URL point into a\nsection of a plain text file) in plain text output. All those are\n_common_ ways of making references, and certainly \"the net\" has not\ndecided to pick any of those exclusively.\n\nThat the particular format \"info\" _also_ is able to represent the\nrespective information originally written into _Texinfo_ source is\nhardly a disadvantage.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49853","messageId":"20070805095928.GA15949@coredump.intra.peff.net","threadId":"9373","inReplyTo":"85abt6b91w.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-08-05T09:59:28Z","receivedAt":"2007-08-05T09:59:28Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Aug 05, 2007 at 11:54:51AM +0200, David Kastrup wrote:\n\n> >> (info \"(gcc) Extended Asm\")\n> >> \n> >> and when you are reading mail in Emacs, you can click on that line\n> >> and get to the respective page in a manual comprising hundreds of\n> >> pages.\n> >\n> > Ugh. A documentation referencing system that works only in one\n> > particular editor,\n> \n> That works in readers of the info format. Do HTML references work\n> outside of HTML readers?\n\nI'm not talking about the _format_, I'm talking about the _referencing\nsystem_. In other words, because URLs are a standard, there are\nthousands of programs which recognize them and can find the resource\nthey mention (which in turn, may spawn an info reader, an html reader,\nor some other interpreter).\n\nWhat software is going to recognize (info \"(gcc) Extended Asm\") in your\nemail and realize that it's a reference to another document? None,\nexcept emacs.\n\nThough I don't especially like the info format or readers, my argument\nhere isn't against it. It is against the feature you mentioned being a\nsubstantial benefit, since a large part of the world isn't reading their\nemail in emacs.\n\n-Peff\n"},{"id":"49858","messageId":"851weib7v3.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"20070805095928.GA15949@coredump.intra.peff.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T10:20:32Z","receivedAt":"2007-08-05T10:20:32Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Jeff King writes:\n\n> On Sun, Aug 05, 2007 at 11:54:51AM +0200, David Kastrup wrote:\n>\n>> >> (info \"(gcc) Extended Asm\")\n>> >> \n>> >> and when you are reading mail in Emacs, you can click on that line\n>> >> and get to the respective page in a manual comprising hundreds of\n>> >> pages.\n>> >\n>> > Ugh. A documentation referencing system that works only in one\n>> > particular editor,\n>> \n>> That works in readers of the info format. Do HTML references work\n>> outside of HTML readers?\n>\n> I'm not talking about the _format_, I'm talking about the _referencing\n> system_. In other words, because URLs are a standard, there are\n> thousands of programs which recognize them and can find the resource\n> they mention (which in turn, may spawn an info reader, an html reader,\n> or some other interpreter).\n\nWell, just for kicks I let firefox loose on\n\ninfo:gcc#Extended Asm\n\nIt passed this off to the GNOME help browser, which displayed\n\"Loading...\", used up 4 seconds of CPU time and 100M of memory, and\nthen hanged itself with a spinning cursor.\n\nInteresting. Starting the help browser manually and typing the URL\nin, however, works. It just seems to suicide when firefox tells it\nabout URLs.\n\n> What software is going to recognize (info \"(gcc) Extended Asm\") in\n> your email and realize that it's a reference to another document?\n> None, except emacs.\n\nSure. So use the above syntax.\n\n> Though I don't especially like the info format or readers, my\n> argument here isn't against it. It is against the feature you\n> mentioned being a substantial benefit, since a large part of the\n> world isn't reading their email in emacs.\n\nSo write it as a URL, if you want to.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49859","messageId":"20070805102242.GA17000@coredump.intra.peff.net","threadId":"9373","inReplyTo":"851weib7v3.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-08-05T10:22:42Z","receivedAt":"2007-08-05T10:22:42Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:\n\n> Well, just for kicks I let firefox loose on\n> \n> info:gcc#Extended Asm\n\nOK, I didn't know there was a URL style defined for info. Thanks for\npointing it out.\n\n-Peff\n"},{"id":"49861","messageId":"85ps229sck.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"20070805102242.GA17000@coredump.intra.peff.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T10:40:59Z","receivedAt":"2007-08-05T10:40:59Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Jeff King writes:\n\n> On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:\n>\n>> Well, just for kicks I let firefox loose on\n>> \n>> info:gcc#Extended Asm\n>\n> OK, I didn't know there was a URL style defined for info.\n\nNeither did I, actually. If anybody would actually use them, I'd have\nto teach firefox to pass them off to Emacs.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49866","messageId":"85y7gq8btz.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"85ps229sck.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T11:23:04Z","receivedAt":"2007-08-05T11:23:04Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"David Kastrup writes:\n\n> Jeff King writes:\n>\n>> On Sun, Aug 05, 2007 at 12:20:32PM +0200, David Kastrup wrote:\n>>\n>>> Well, just for kicks I let firefox loose on\n>>> \n>>> info:gcc#Extended Asm\n>>\n>> OK, I didn't know there was a URL style defined for info.\n>\n> Neither did I, actually. If anybody would actually use them, I'd have\n> to teach firefox to pass them off to Emacs.\n\nThe details can be found in .\n\nIf you find this syntax referring to a man page weird, you should\nprobably not complain about me writing (info \"(gcc) Extended Asm\") as\na reference.\n\nWhen there are few readers of a format, it is easier to use a\n\"natural\" spelling.\n\nAnyway, I have seen in a posting about mathematics someone write an\nequation including sqrt(3) and saw Emacs highlight this expression.\nSo I clicked on it. And Emacs opened the man-page. Definitely not\nwhat I had expected...\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49915","messageId":"alpine.LFD.0.999.0708051004480.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85bqdmctcl.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-05T17:08:39Z","receivedAt":"2007-08-05T17:08:39Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sun, 5 Aug 2007, David Kastrup wrote:\n> \n> So please get a grip and focus on what we were actually talking\n> about. Not Emacs, but rather documentation formats.\n\nYou're the one who started talking about me expecting people to use *my* \neditor. I had never done that. I had talked about the _reverse_: the \nidiocy of emacs users expecting people to use that bloated piece of \ncrap-ware.\n\n> > Man-pages with man.\n> \n> Actually, Emacs \"woman\" does a pretty good job with those, offers\n> convenient man page name completion and works on Windows and similar\n> platforms without needing\n\nSee? Can you not see that normal users don't want to have some random \nemacs crap? In fact, even GNU emacs users (apart from the ones that have \nused it for more than a decade) don't do it.\n\nSo stop this *insane* insistence of emacs. You should learn to just assume \nthat people don't even have it installed!\n\nAnything that works with some random emacs mode is a total non-usable \npiece of crap as far as most users are concerned.\n\n> Focus. How do you propose to manage documention of a hundred pages an\n> more conveniently, finding information easily by text, index,\n> hyperlinks? A single large HTML page? A documentation directory full\n> of *.txt files which you can grep through (not that Emacs would not be\n> useful for that, too)?\n\nOh, a single large html page is certainly better than emacs and info, \nabsolutely. Ask *any* normal person.\n\nThe fact that you cannot see that fact is a sign of your personal (and \nrather odd) preferences.\n\n\t\t\tLinus\n"},{"id":"49920","messageId":"85bqdlj1lh.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708051004480.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T18:08:42Z","receivedAt":"2007-08-05T18:08:42Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Linus Torvalds writes:\n\n> On Sun, 5 Aug 2007, David Kastrup wrote:\n>> \n>> So please get a grip and focus on what we were actually talking\n>> about. Not Emacs, but rather documentation formats.\n>\n> You're the one who started talking about me expecting people to use\n> *my* editor. I had never done that. I had talked about the\n> _reverse_: the idiocy of emacs users expecting people to use that\n> bloated piece of crap-ware.\n\nYes, and it was not the topic. So I pointed out your hypocrisy since\n_you_ talk about editor preferences and \"normal\" people, while\npreferring an editor yourself that is used by far fewer people.\n\nYou are still unable to focus on anything but name-calling and editors\nrather than documentation formats.\n\n> So stop this *insane* insistence of emacs. You should learn to just\n> assume that people don't even have it installed!\n\nWe were discussing Texinfo, not Emacs. Please focus.\n\n> Anything that works with some random emacs mode is a total\n> non-usable piece of crap as far as most users are concerned.\n\nAgain, you are speaking for the rest of the world, conveniently\nignoring that more people use such a system than the one you use. But\nplease stop focusing on editors and focus on documentation formats.\n\n>> Focus. How do you propose to manage documention of a hundred pages\n>> an more conveniently, finding information easily by text, index,\n>> hyperlinks? A single large HTML page? A documentation directory\n>> full of *.txt files which you can grep through (not that Emacs\n>> would not be useful for that, too)?\n>\n> Oh, a single large html page is certainly better than emacs and\n> info, absolutely. Ask *any* normal person.\n\nWhich is why books nowadays always come as a single scroll without\nindex and table of contents, right? Ask any normal person.\n\n> The fact that you cannot see that fact is a sign of your personal\n> (and rather odd) preferences.\n\nYes, name-calling and ad hominem attacks again. It's getting old. So\nyou think a single large html page containing everything in the\ngit/Documentation directory is the way we should organize git\ndocumentation for the sake of the users? All manual pages one after\nthe other, and some text in between explaining the connections? In\none large file?\n\nWhile harping on my sanity and normality because of contemplating\nsomething more structured?\n\nPlease.\n\nFor what it's worth: Texinfo documents _can_ be converted into a\nsingle HTML file as _well_ as a hierarchically split document with a\nhyperlinked index. So using Texinfo as a source format would _still_\nallow preparing HTML in both multiple and single file form for the\nsake of Torvalds-normal users.\n\nPlease try to remember that Texinfo is a _source_ format, and it\nproduces reasonably hyperrefed and coherent PDF and HTML documents as\nwell as plain ASCII. That it is also able to produce working info\nfiles should not bother you.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49923","messageId":"alpine.LFD.0.999.0708051118590.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85bqdlj1lh.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-05T18:23:00Z","receivedAt":"2007-08-05T18:23:00Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sun, 5 Aug 2007, David Kastrup wrote:\n> \n> You are still unable to focus on anything but name-calling and editors\n> rather than documentation formats.\n\nNo, it's the same thing.\n\nI started out by saying that Texinfo is horrible. It's horrible because it \ndoesn't *buy* you anything. The only thing it buys you (the \"info\" format) \nis totally irrelevant, which I tried to explain.\n\nAsciiDoc is much nicer. It does everything that Texinfo does for us, and \nit's readable on its own as plain text, something Texinfo isn't.\n\nSo by advocating Texinfo, you're advocating something that is OBJECTIVELY \nWORSE than what we have now.\n\nAnd I tried to explain why, by pointing out that info files (which was the \ncase you tried to push as an advantage) aren't actually an advantage to \nany normal user.\n\n\t\t\tLinus\n"},{"id":"49924","messageId":"Pine.LNX.4.64.0708051933180.14781@racer.site","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708051118590.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-08-05T18:35:23Z","receivedAt":"2007-08-05T18:35:23Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 5 Aug 2007, Linus Torvalds wrote:\n\n> > You are still unable to focus on anything but name-calling and editors \n> > rather than documentation formats.\n> \n> No, it's the same thing.\n\nHehe. Statements like the first made me set up a certain procmail filter. \nMade me much happier, too.\n\nAnd now I see only one side of the conversation, which is actually pretty \nfunny... much like listening in into a heated phone conversation, and \nguessing what the other one said. *grin*\n\nCiao,\nDscho\n"},{"id":"49926","messageId":"85y7gphkdd.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708051118590.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T19:06:06Z","receivedAt":"2007-08-05T19:06:06Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Linus Torvalds writes:\n\n> On Sun, 5 Aug 2007, David Kastrup wrote:\n>> \n>> You are still unable to focus on anything but name-calling and editors\n>> rather than documentation formats.\n>\n> No, it's the same thing.\n>\n> I started out by saying that Texinfo is horrible. It's horrible\n> because it doesn't *buy* you anything.\n\nNo, that's not what makes it horrible.\n\n> The only thing it buys you (the \"info\" format) is totally\n> irrelevant, which I tried to explain.\n\nBy calling everybody names that would dare using it. That's not\nreally an explanation.\n\n> AsciiDoc is much nicer. It does everything that Texinfo does for us,\n> and it's readable on its own as plain text, something Texinfo isn't.\n\nReadable plain text can be generated from Texinfo, so that is a red\nherring.\n\n> So by advocating Texinfo, you're advocating something that is\n> OBJECTIVELY WORSE than what we have now.\n>\n> And I tried to explain why, by pointing out that info files (which\n> was the case you tried to push as an advantage) aren't actually an\n> advantage to any normal user.\n\nLinus, your \"normal user\" does not get any documentation that can\nusefully be employed for navigating a large body of documentation.\n\nAnyway, this particular flame feast might be somewhat irrelevant: I\nhave read up a bit on AsciiDoc and Docbook, and it would appear that\nquite a lot of what is needed for putting the required information for\nindexes and nodes and other structural information is there in both\nformats, and there is a tool called docbook2X that can presumably\nconvert to Texinfo (currently it barfs on the usermanual). So\nbasically a lot can be achieved by structuring the existing\ndocumentation into book form in AsciiDoc and peppering it with\nindexing (apparently only a single index is possible) and other\nstructural information.\n\nThis will make the AsciiDoc sources less readable, while improving the\nstructural information content of the generated output, presumably\nalso when not going via Texinfo conversion.\n\nRestructuring the available documentation into something that _can_ be\nused as a coherent book, whether as a single PDF, single or multiple\nHTML pages or even (avaunt!) info is probably not too horrible a\nlong-term prospect, and if info gives you the heebies, just don't call\n\"make info install-info\", and you'll never get contaminated with it.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49927","messageId":"85tzrdhk4d.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"Pine.LNX.4.64.0708051933180.14781@racer.site","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T19:11:30Z","receivedAt":"2007-08-05T19:11:30Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Johannes Schindelin writes:\n\n> On Sun, 5 Aug 2007, Linus Torvalds wrote:\n>\n>> > You are still unable to focus on anything but name-calling and editors \n>> > rather than documentation formats.\n>> \n>> No, it's the same thing.\n>\n> Hehe. Statements like the first made me set up a certain procmail\n> filter. Made me much happier, too.\n\nInteresting stance for somebody who has complained violently that I\nshould provide him with personal copies of mails to the list. So you\nneed those copies in order to keep your procmail busy...\n\n> And now I see only one side of the conversation, which is actually\n> pretty funny... much like listening in into a heated phone\n> conversation, and guessing what the other one said. *grin*\n\nYou also get a chance of vetoing my patches only after they have been\napplied, which happened a few times already.\n\nTo each his own, I guess.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49930","messageId":"alpine.LFD.0.999.0708051221290.5037@woody.linux-foundation.org","threadId":"9373","inReplyTo":"85bqdlj1lh.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2007-08-05T19:29:09Z","receivedAt":"2007-08-05T19:29:09Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sun, 5 Aug 2007, David Kastrup wrote:\n>\n> > The fact that you cannot see that fact is a sign of your personal\n> > (and rather odd) preferences.\n> \n> Yes, name-calling and ad hominem attacks again.\n\nNo. Emacs _is_ odd. It's not even installed by default on most modern \nLinux distributions.\n\nThere's no name-calling there. That's just a solid fact. You are \nemacs-fixated when you keep on trying to bring up totally irrelevant \nemacs issues.\n\n> Please try to remember that Texinfo is a _source_ format, and it\n> produces reasonably hyperrefed and coherent PDF and HTML documents as\n> well as plain ASCII. That it is also able to produce working info\n> files should not bother you.\n\nYou do not even know what you are talking about.\n\nAsciiDoc is *also* a source format. But the source format is already \nreadable IN ITSELF. Which is the whole point!\n\nI don't even bother to run \"make doc\". I bet that is true of almost \neverybody else too. Why? Because the *source* format we use (asciidoc) is \nalready basically as readable as any formatted man-page would ever be.\n\nYou don't have to even *know* that they are AsciiDoc pages - they're just \ncalled \"*.txt\", and that's what they are. Text. With very minimal fixups \nthat *allow* them to be used as source for things like html, and \nadmittedly you get prettier output, but it really is perfectly \nstraightforward to just read them, in ways that pretty much no other \ndocumentation format allows. Everybody else puts very intrusive crap in \nthere, so that you *have* to be aware of in ways you don't need to worry \nabout in AsciiDoc.\n\nHeaders? Lists? They look like headers and lists in the .txt files. No \nneed to think about it as a reader. \n\nSee? Texinfo is decidedly inferior. But you don't have to take it so \npersonally. So is pretty much anything else. Anything XML/SGML is even \n*worse*.\n\n\t\t\tLinus\n"},{"id":"49940","messageId":"85bqdlhge0.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"85y7gphkdd.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T20:32:07Z","receivedAt":"2007-08-05T20:32:07Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"David Kastrup writes:\n\n> Linus Torvalds writes:\n>\n>> So by advocating Texinfo, you're advocating something that is\n>> OBJECTIVELY WORSE than what we have now.\n>>\n>> And I tried to explain why, by pointing out that info files (which\n>> was the case you tried to push as an advantage) aren't actually an\n>> advantage to any normal user.\n>\n> Linus, your \"normal user\" does not get any documentation that can\n> usefully be employed for navigating a large body of documentation.\n>\n> Anyway, this particular flame feast might be somewhat irrelevant: I\n> have read up a bit on AsciiDoc and Docbook.\n\nOk, it turns out that\n\ndocbook2x-texi --info --to-stdout usermanual.xml >usermanual.info\n\ncranks out (after a few inexplicable warnings/errors) a completely\nfunctional info file. The one thing that is conspicously missing is\nindexing and info-dir information, and that's because it is not in the\nsource in the first place.\n\nWhether you want to believe it or not, this already helps me\n_considerably_ find my way around git.\n\nSo info, at least for the manual, can at the current point of time be\nsupported by merely adding Makefile targets.\n\nSince an index is useful for other output formats, I don't think that\nthere should be objections to adding indexing info into the manual.\nThis takes the AsciiDoc form of ((primary)) for a primary entry\nappearing in the text, and (((primary[, secondary[, third]]))) for a\nhierarchical entry not appearing in the text itself.\n\nCorrect?\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49944","messageId":"46B6446D.4030607@gnu.org","threadId":"9373","inReplyTo":"alpine.LFD.0.999.0708051221290.5037@woody.linux-foundation.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Bruce Korb","fromEmail":"bkorb@gnu.org","sentAt":"2007-08-05T21:43:09Z","receivedAt":"2007-08-05T21:43:09Z","isPatch":false,"sender":{"key":"bkorb@gnu.org","avatar":null},"body":"Linus Torvalds wrote:\n>> Yes, name-calling and ad hominem attacks again.\n> \n> No. Emacs _is_ odd. It's not even installed by default on most modern \n> Linux distributions.\n\nHi Linus,\n\nThus disparaging distributions that do install it. I've not had\nto pull any extra packages to get it so far, but I only update\nevery few years. I've been a happy emacs user for 24 years.\n\n> There's no name-calling there. That's just a solid fact.\n\nThe name calling is unseemly on all sides.\n\n>> Please try to remember that Texinfo is a _source_ format, and it\n>> produces reasonably hyperrefed and coherent PDF and HTML documents as\n>> well as plain ASCII. That it is also able to produce working info\n>> files should not bother you.\n> \n> You do not even know what you are talking about.\n> \n> AsciiDoc is *also* a source format. But the source format is already \n> readable IN ITSELF. Which is the whole point!\n\nReadable, just not writable. It's markup language is a bunch\nof special characters that require familiarity to understand.\nSure, you can peruse the text just fine, but why should this\nsort of thing:\n\n = My Doc Title =\n\nbe preferred to:\n\n @settitle My Doc Title\n\n@chapter, @section, @subsection really make a lot more sense to me\nthan this sort of cruft (my disparaging term):\nLevel 0 (top level): ======================\nLevel 1: ----------------------\nLevel 2: ~~~~~~~~~~~~~~~~~~~~~~\nLevel 3: ^^^^^^^^^^^^^^^^^^^^^^\nLevel 4 (bottom level): ++++++++++++++++++++++\n\nIt really boils down to preferences and familiarity and should\nnot degenerate into nasty name calling.\n\n> Headers? Lists? They look like headers and lists in the .txt files. No \n> need to think about it as a reader. \n\nSo do well-formatted .texi docs. I don't really like anything\nother than WYSIWYG, but that doesn't lend it self to reformatting\ninto man pages et al.\n\n> See? Texinfo is decidedly inferior. But you don't have to take it so \n> personally. So is pretty much anything else. Anything XML/SGML is even \n> *worse*.\n\nBah! They all have their drawbacks and preferences are going to weight\ndrawbacks differently.\n\nSo let's all dislike all our choices, eh? Cheers - Bruce\n"},{"id":"49946","messageId":"857io9hblv.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"46B6446D.4030607@gnu.org","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-05T22:15:24Z","receivedAt":"2007-08-05T22:15:24Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Bruce Korb writes:\n\n> Linus Torvalds wrote:\n>\n>> AsciiDoc is *also* a source format. But the source format is\n>> already readable IN ITSELF. Which is the whole point!\n>\n> Readable, just not writable. It's markup language is a bunch of\n> special characters that require familiarity to understand.\n\nWell, one problem I find that the documentation of both Asciidoc and\nthe connected Docbook toolchain is horribly subpar.\n\nOne part of the problem is that asciidoc.txt is written in Asciidoc,\nand so you can't pick apart markup from content in the explanations\nwhen reading the \"readable in itself\" documents.\n\nAnother problem is that most of the details of conversion to Docbook,\nand what results in what XML output, are completely glossed over. And\nthen there are further problems in that downstream Docbook processors\nare documented even worse.\n\nThen there is the problem that the markup can be redefined: the\nsectioning underlines explained in the asciidoc documentation differ\nfrom that _used_ in the documentation and again from that used in the\ngit documentation.\n\nNow I can, in fact, use\ndocbook2x-texi --info --to-stdout user-manual.xml >user-manual.info\nand get a working info file: not just basically working, but quite\nfine (missing an index, though).\n\nSo there are \"minor details\" to fill in, like generated file names and\ninfo directory entries. Would you think that there is _any_ way of\nfinding out how to represent this in Docbook, or if you find out that,\nhow to get it from Asciidoc into Docbook?\n\nForget it.\n\nOr things like including the manual pages in an appendix or elsewhere.\nAny chance for that? Slim, at least for me.\n\nTexinfo source certainly looks less pretty than Asciidoc, but then\nmakeinfo can produce plain text output from it looking quite like\nAsciidoc. And whatever you may think about Texinfo as a format and\nthe generated info files and their readers: it is damn well\ndocumented.\n\nAsciidoc is quite readonly in many respects at the moment for me, and\nI don't even know where to start in order to fix that.\n\nAnd it does not help that there are multiple conversions involved with\na pretty opaque in-between XML representation. In contrast, Texinfo\nhas a single well-documented source format and direct converters to\nthe target formats.\n\nAnd its syntax is straightforward enough to write additional\nconverters if one wants to (makeinfo can even produce Docbook output,\nso perhaps I may have a chance to reverse-engineer some required\ninformation from there).\n\nWhatever. It is pretty clear that Texinfo is not going to be\ninteresting enough to maintain for most git developers to continue\nthis particular thread, as it won't progress beyond a simple and ugly\nadvocacy and name-calling thread.\n\nAnyway, the necessary structural information (indexing, directory info\netc) presumably can be spliced into Asciidoc documents once somebody\nfinds out how to do this, and then Texinfo can be _generated_ from it\nfor those who need it.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"49950","messageId":"20070805223105.GC12168@fieldses.org","threadId":"9373","inReplyTo":"857io9hblv.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-08-05T22:31:05Z","receivedAt":"2007-08-05T22:31:05Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Mon, Aug 06, 2007 at 12:15:24AM +0200, David Kastrup wrote:\n> Or things like including the manual pages in an appendix or elsewhere.\n> Any chance for that? Slim, at least for me.\n\nI'd like to do exactly that at some point. I was hoping it would be as\nsimple as just adding a bunch of include:: statements, but there's\nprobably some more obstacles. If someone had the time to look into what\nwould be required to get it working, I'd be grateful.\n\n--b.\n"},{"id":"49955","messageId":"7vr6mheem0.fsf@assigned-by-dhcp.cox.net","threadId":"9373","inReplyTo":"85bqdlj1lh.fsf@lola.goethe.zz","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-05T23:38:47Z","receivedAt":"2007-08-05T23:38:47Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"David Kastrup writes:\n\n>> So stop this *insane* insistence of emacs. You should learn to just\n>> assume that people don't even have it installed!\n>\n> We were discussing Texinfo, not Emacs. Please focus.\n\nI would welcome if the set of our documentation output formats\nincluded *.info pages.\n\nHowever, as the input format, texinfo _is_ painful. AsciiDoc is\n100x easier. I've written documentaiton in texinfo format in\nthe past, and one thing I found quite painful was maintaining\nthe node header with prev/next links --- tedious, error prone\nand boring. There is no good editor to help you maintain them\nother than Emacs texinfo mode as far as I know.\n"},{"id":"49960","messageId":"87abt5h65u.fsf@catnip.gol.com","threadId":"9373","inReplyTo":"7vr6mheem0.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"Miles Bader","fromEmail":"miles@gnu.org","sentAt":"2007-08-06T00:13:01Z","receivedAt":"2007-08-06T00:13:01Z","isPatch":false,"sender":{"key":"miles@gnu.org","avatar":"https://gravatar.com/avatar/01069b69593af7bff28e2f97afeb3644ae6fe2f5f56cb3a8cf34c5fb8c36efe5?d=mp&s=160"},"body":"Junio C Hamano writes:\n> I've written documentaiton in texinfo format in the past, and one\n> thing I found quite painful was maintaining the node header with\n> prev/next links --- tedious, error prone and boring.\n\nActually, the prev/next/up parts of @node are optional in the input file\n-- if you just leave them out, makeinfo will fill them in for you.\n\n-miles\n\n-- \n\"Suppose we've chosen the wrong god. Every time we go to church we're\njust making him madder and madder.\" -- Homer Simpson\n"},{"id":"49986","messageId":"85y7gpfc85.fsf@lola.goethe.zz","threadId":"9373","inReplyTo":"7vr6mheem0.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-06T05:44:58Z","receivedAt":"2007-08-06T05:44:58Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Junio C Hamano writes:\n\n> David Kastrup writes:\n>\n>>> So stop this *insane* insistence of emacs. You should learn to just\n>>> assume that people don't even have it installed!\n>>\n>> We were discussing Texinfo, not Emacs. Please focus.\n>\n> I would welcome if the set of our documentation output formats\n> included *.info pages.\n>\n> However, as the input format, texinfo _is_ painful. AsciiDoc is\n> 100x easier.\n\nIf you are able to figure out what to write. Can you tell me how to\ninclude one of the man pages in an appendix, with appropriate\nsubstructure? I can't. It might be easy, but I find it impossible\nto guess from the information just how.\n\n> I've written documentaiton in texinfo format in the past, and one\n> thing I found quite painful was maintaining the node header with\n> prev/next links --- tedious, error prone and boring.\n\n File: texinfo, Node: makeinfo Pointer Creation, Next: anchor, Prev: node, Up: Nodes\n\n 6.4 Creating Pointers with `makeinfo'\n =====================================\n\n The `makeinfo' program has a feature for automatically determining node\n pointers for a hierarchically organized document.\n\n When you take advantage of this feature, you do not need to write the\n `Next', `Previous', and `Up' pointers after the name of a node.\n However, you must write a sectioning command, such as `@chapter' or\n `@section', on the line immediately following each truncated `@node'\n line (except that comment lines may intervene).\n\n In addition, you must follow the `Top' `@node' line with a line\n beginning with `@top' to mark the `Top' node in the file. *Note\n `@top': makeinfo top.\n\n Finally, you must write the name of each node (except for the `Top'\n node) in a menu that is one or more hierarchical levels above the\n node's hierarchical level.\n\n This implicit node pointer insertion feature in `makeinfo' relieves\n you from the need to update menus and pointers manually or with Texinfo\n mode commands. (*Note Updating Nodes and Menus::.)\n\n> There is no good editor to help you maintain them other than Emacs\n> texinfo mode as far as I know.\n\nThen don't maintain them. It is not necessary.\n\nAnyway, I suggest that people wanting to continue to berave me for\ntaking the word Texinfo into my mouth do this off-list. It is very\nmuch clear that Texinfo is no-go as a source documentation format for\nGit: it makes a considerable ratio of developers foam at the mouth.\nAnd that simply rules it out.\n\nIt also turns out that makeinfo2x-texi is able to produce rather good\nTexinfo from stuff written for book output with Asciidoc. Yes, there\nare details missing, but it is nothing one could not slide in with\nsed into the Texinfo file. And adding the absent indexing information\ncan be done in Asciidoc: that is documented.\n\nIn contrast, I have just tried using makeinfo --docbook on AUCTeX\nTexinfo documentation, and the docbook XML it produces is not always\nproperly nested, and when one corrects that, the problems with\nprocessing that just start: that seems not really tested, at least\nwith makeinfo 4.8.\n\nSo there is a good Docbook->info path, but not the other way round.\nAnyway, you wrote:\n\n> I would welcome if the set of our documentation output formats\n> included *.info pages.\n\nAt least for the user manual, I can support this (without index) in a\ndozen lines of makefile code and another dozen lines of sed (for\nadding the top/dir entry information). Yes, this caught me quite by\nsurprise. For the indexing, of course one will have to insert the\nappropriate Asciidoc markup into the source files. I can also work on\nthat, but it should likely be a colloborative effort: it leads to a\nworking Index also in the PDF output without the need to involve\nTexinfo.\n\nAs for making the man pages part of the main manual: I don't know my\nway around Asciidoc enough to be able to do this. It might be\npossible to fudge around this issue with sed again, converting the\nmanual page sources to book section sources. I am sure there is a\nmore elegant way to do this sort of transformation/conversion either\non the Asciidoc or XML level, but it's beyond me.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"50119","messageId":"87tzrbee8a.fsf@morpheus.local","threadId":"9373","inReplyTo":"7vzm18jg7p.fsf@assigned-by-dhcp.cox.net","subject":"Re: [ANNOUNCE] GIT 1.5.3-rc4","fromName":"David Kågedal","fromEmail":"davidk@lysator.liu.se","sentAt":"2007-08-07T12:11:33Z","receivedAt":"2007-08-07T12:11:33Z","isPatch":false,"sender":{"key":"davidk@lysator.liu.se","avatar":"https://avatars.githubusercontent.com/u/60530?v=4"},"body":"Junio C Hamano writes:\n\n> GIT v1.5.3 Release Notes (draft)\n> ========================\n>\n> Updates since v1.5.2\n> --------------------\n>\n> * The commit walkers other than http are officially deprecated,\n> but still supported for now.\n\nThis will not make sense to a lot of people. I've been around here\nsince git was invented, and I think I can guess what it means, but I'm\nnot completely sure. A \"commit walker\" is something that probably\nonly a few core git developers know what it is.\n\nPlease remember to give a second of thought to who will be reading\nthis. It is very hard to determine from this short message who will\nbe affected, and in what way.\n\n-- \nDavid Kågedal\n"},{"id":"50175","messageId":"86wsw65tud.fsf@lola.quinscape.zz","threadId":"9373","inReplyTo":"20070805223105.GC12168@fieldses.org","subject":"Man-pages in user manual (was: [ANNOUNCE] GIT 1.5.3-rc4)","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-08-08T08:11:22Z","receivedAt":"2007-08-08T08:11:22Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"\"J. Bruce Fields\" writes:\n\n> On Mon, Aug 06, 2007 at 12:15:24AM +0200, David Kastrup wrote:\n>> Or things like including the manual pages in an appendix or elsewhere.\n>> Any chance for that? Slim, at least for me.\n>\n> I'd like to do exactly that at some point. I was hoping it would be as\n> simple as just adding a bunch of include:: statements, but there's\n> probably some more obstacles. If someone had the time to look into what\n> would be required to get it working, I'd be grateful.\n\nWell, I posted already a patch set (or rather, several iterations)\nthat built info documentation from the user manual. I only got a\nsingle comment from Jakub about notices in INSTALL, and about the awk\ndependency. The last iteration from yesterday addressed both AFAICT.\nSince it does not affect existing Makefile targets at all, I hope that\nit may end up in 1.5.3.\n\nHowever, independently from info, I think the git documentation should\nbe structured into one or more standalone documents that make sense as\na single DocBook document (and ultimately a printed PDF) each. Of\ncourse this will benefit generating info, but it will also give other\npeople better documentation into their hands.\n\nI digress.\n\nConcerning your request\n\n> If someone had the time to look into what would be required to get\n> it working, I'd be grateful.\n\nI did some digging and some trying. The inclusion of the manual pages\nwill not work out of the box: they have different markup and logical\nsectioning levels.\n\nHowever, AsciiDoc does provide mechanisms that could be used for\nincluding this sort of stuff, by just matching the markup used in the\nman page sources and replacing it with the appropriate headers or\nmarkup for the DocBook case.\n\nTo figure this out, read up on the following parts:\n\n\n\n\nIt turns out, however, that this may be doing it the hard way: There\nis a way to have sections/appendices consisting of just manual pages:\n\n\n\nSo it may be easiest to just create a section in the XML,\ninclude the man pages in there, and see what the various DocBook\nconverters make of that.\n\nOf course, in such a document one would want to change the gitlink\nmacros to actually point to the included reference rather than an\noutside resource.\n\nThat would have to be done in Documentation/asciidoc.conf as far as I\ncan see.\n\nThere are already autogenerated files cmds*.txt that contain lists of\nthe various manpages. One could either use them directly (with a\ntemporary gitlink definition that includes a manual page rather than\nreferring to it), or generate similar files with a more\nstraightforward relation of content and behavior.\n\n-- \nDavid Kastrup\n"}]}