{"thread":{"id":"10121","subject":"WIP: asciidoc replacement","startedAt":"2007-10-03T00:42:00Z","lastAt":"2007-10-04T22:49:56Z","messageCount":25,"participants":["Johannes Schindelin","Sam Vilain","Junio C Hamano","Jeff King","Wincent Colaiuta","David Kastrup","Sam Ravnborg","J. Bruce Fields","Martin Langhoff"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"54631","messageId":"Pine.LNX.4.64.0710030133020.28395@racer.site","threadId":"10121","inReplyTo":null,"subject":"WIP: asciidoc replacement","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-10-03T00:42:00Z","receivedAt":"2007-10-03T00:42:00Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nI do not want to depend on more than necessary in msysGit, and therefore I \nstarted to write an asciidoc replacement.\n\nSo here it is: a perl script that does a good job on many .txt files in \nDocumentation/, although for some it deviates from \"make man\"'s output, \nand for others it is outright broken.  It is meant to be run in \nDocumentation/.\n\nMy intention is not to fix the script for all cases, but to make patches \nto Documentation/*.txt themselves, so that they are more consistent (and \nincidentally nicer to the script).\n\nNow, I hear you already moan: \"But Dscho, you know you suck at Perl!\"\n\nYeah, I know, but maybe instead of bashing on me (pun intended), you may \nwant to enlighten me with tips how to make it nicer to read.  (Yes, there \nare no comments; yes, I will gladly add them where appropriate; yes, html \nis just a stub.)\n\nSo here, without further ado, da script:\n\n-- snip --\n#!/usr/bin/perl\n\n$conv = new man_page();\n$conv->{manual} = 'Git Manual';\n$conv->{git_version} = 'Git ' . `cat ../GIT-VERSION-FILE`;\n$conv->{git_version} =~ s/GIT_VERSION = //;\n$conv->{git_version} =~ s/-/\\\\-/;\n$conv->{git_version} =~ s/\\n//;\n$conv->{date} = `date +%m/%d/%Y`;\n$conv->{date} =~ s/\\n//;\n\n$par = '';\nhandle_file($ARGV[0]);\n$conv->finish();\n\nsub handle_text {\n\tif ($par =~ /^\\. /s) {\n\t\tmy @lines = split(/^\\. /m, $par);\n\t\tshift @lines;\n\t\t$conv->enumeration(\\@lines);\n\t} elsif ($par =~ /^\\* /s) {\n\t\tmy @lines = split(/^\\* /m, $par);\n\t\tshift @lines;\n\t\t$conv->enumeration(\\@lines, 'unnumbered');\n\t} elsif ($par =~ /^\\[verse\\]/) {\n\t\t$par =~ s/\\[verse\\] *\\n?//;\n\t\t$conv->verse($par);\n\t} elsif ($par =~ /^(\\t|  +)/s) {\n\t\t$par =~ s/^$1//mg;\n\t\t$par =~ s/^\\+$//mg;\n\t\t$conv->indent($par);\n\t} elsif ($par =~ /^([^\\n]*)::\\n((\\t|  +).*)$/s) {\n\t\tmy ($first, $rest, $indent) = ($1, $2, $3);\n\t\t$rest =~ s/^\\+$//mg;\n\t\twhile ($rest =~ /^(.*?\\n\\n)--+\\n(.*?\\n)--+\\n\\n(.*)$/s) {\n\t\t\tmy ($pre, $verb, $post) = ($1, $2, $3);\n\n\t\t\t$pre =~ s/^(\\t|$indent)//mg;\n\t\t\tif ($first ne '') {\n\t\t\t\t$conv->begin_item($first, $pre);\n\t\t\t\t$first = '';\n\t\t\t} else {\n\t\t\t\t$conv->normal($pre);\n\t\t\t}\n\n\t\t\t$conv->verbatim($verb);\n\t\t\t$rest = $post;\n\t\t}\n\t\t$rest =~ s/^(\\t|$indent)//mg;\n\t\tif ($first ne '') {\n\t\t\t$conv->begin_item($first, $rest);\n\t\t} else {\n\t\t\t$conv->normal($rest);\n\t\t}\n\t\t$conv->end_item();\n\t} elsif ($par =~ /^-+\\n(.*\\n)-+\\n$/s) {\n\t\t$conv->verbatim($1);\n\t} else {\n\t\t$conv->normal($par);\n\t}\n\t$par = '';\n}\n\nsub handle_file {\n\tmy $in;\n\topen($in, '<' . $_[0]);\n\twhile (<$in>) {\n\t\tif (/^=+$/) {\n\t\t\tif ($par ne '' && length($_) >= length($par)) {\n\t\t\t\t$conv->header($par);\n\t\t\t\t$par = '';\n\t\t\t\tnext;\n\t\t\t}\n\t\t} elsif (/^-+$/) {\n\t\t\tif ($par ne '' && length($_) >= length($par)) {\n\t\t\t\t$conv->section($par);\n\t\t\t\t$par = '';\n\t\t\t\tnext;\n\t\t\t}\n\t\t} elsif (/^~+$/) {\n\t\t\tif ($par ne '' && length($_) >= length($par)) {\n\t\t\t\t$conv->subsection($par);\n\t\t\t\t$par = '';\n\t\t\t\tnext;\n\t\t\t}\n\t\t} elsif (/^\\[\\[(.*)\\]\\]$/) {\n\t\t\thandle_text();\n\t\t\t$conv->anchor($1);\n\t\t\tnext;\n\t\t} elsif (/^$/) {\n\t\t\tif ($par =~ /^-+\\n.*[^-]\\n$/s) {\n\t\t\t\t# fallthru; is verbatim, but needs more.\n\t\t\t} elsif ($par =~ /::\\n$/s) {\n\t\t\t\t# is item, but needs more.\n\t\t\t\tnext;\n\t\t\t} else {\n\t\t\t\thandle_text();\n\t\t\t\tnext;\n\t\t\t}\n\t\t} elsif (/^include::(.*)\\[\\]$/) {\n\t\t\thandle_text();\n\t\t\thandle_file($1);\n\t\t\tnext;\n\t\t}\n\n\t\t# convert \"\\--\" to \"--\"\n\t\ts/\\\\--/--/g;\n\t\t# convert \"\\*\" to \"*\"\n\t\ts/\\\\\\*/*/g;\n\n\t\t# handle gitlink:\n\t\ts/gitlink:([^\\[ ]*)\\[(\\d+)\\]/sprintf \"%s\",\n\t\t\t$conv->get_link($1, $2)/ge;\n\t\t# handle link:\n\t\ts/link:([^\\[ ]*)\\[(.+)\\]/sprintf \"%s\",\n\t\t\t$conv->get_link($1, $2, 'external')/ge;\n\n\t\t$par .= $_;\n\t}\n\tclose($in);\n\thandle_text();\n}\n\npackage man_page;\n\nsub new {\n\tmy ($class) = @_;\n\tmy $self = {\n\t\tsep => '',\n\t\tlinks => [],\n#\t\tgenerator => 'Home grown git txt2man converter'\n\t\tgenerator => 'DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>'\n\t};\n\tbless $self, $class;\n\treturn $self;\n}\n\nsub header {\n\tmy ($self, $text) = @_;\n\t$text =~ s/-/\\\\-/g;\n\n\tif ($self->{preamble_shown} == undef) {\n\t\t$title = $text;\n\t\t$title =~ s/\\(\\d+\\)$//;\n\t\tprint '.\\\"     Title: ' . $title\n\t\t\t. '.\\\"    Author: ' . \"\\n\"\n\t\t\t. '.\\\" Generator: ' . $self->{generator} . \"\\n\"\n\t\t\t. '.\\\"      Date: ' . $self->{date} . \"\\n\"\n\t\t\t. '.\\\"    Manual: ' . $self->{manual} . \"\\n\"\n\t\t\t. '.\\\"    Source: ' . $self->{git_version} . \"\\n\"\n\t\t\t. '.\\\"' . \"\\n\";\n\t}\n\n\t$text =~ tr/a-z/A-Z/;\n\tmy $suffix = \"\\\"$self->{date}\\\" \\\"$self->{git_version}\\\"\"\n\t\t. \" \\\"$self->{manual}\\\"\";\n\t$text =~ s/^(.*)\\((\\d+)\\)$/.TH \"\\1\" \"\\2\" $suffix/;\n\tprint $text;\n\n\tif ($self->{preamble_shown} == undef) {\n\t\tprint '.\\\" disable hyphenation' . \"\\n\"\n\t\t\t. '.nh' . \"\\n\"\n\t\t\t. '.\\\" disable justification (adjust text to left'\n\t\t\t\t. ' margin only)' . \"\\n\"\n\t\t\t. '.ad l' . \"\\n\";\n\t\t$self->{preamble_shown} = 1;\n\t}\n\n\t$self->{last_op} = 'header';\n}\n\nsub section {\n\tmy ($self, $text) = @_;\n\n\t$text =~ tr/a-z/A-Z/;\n\t$text =~ s/^(.*)$/.SH \"\\1\"/;\n\n\tprint $text;\n\n\t$self->{last_op} = 'section';\n}\n\nsub subsection {\n\tmy ($self, $text) = @_;\n\n\t$text =~ s/^(.*)$/.SS \"\\1\"/;\n\n\tprint $text;\n\n\t$self->{last_op} = 'subsection';\n}\n\nsub get_link {\n\tmy ($self, $command, $section, $option) = @_;\n\n\tif ($option eq 'external') {\n\t\tmy $links = $self->{links};\n\t\tpush(@$links, $command);\n\t\t$command =~ s/\\.html$//;\n\t\t$command =~ s/-/ /g;\n\t\tpush(@$links, $command);\n\t\treturn '\\fI' . $command . '\\fR\\&[1]';\n\t} else {\n\t\treturn '\\fB' . $command . '\\fR(' . $section . ')';\n\t}\n}\n\nsub common {\n\tmy ($self, $text, $option) = @_;\n\n\t# escape backslashes, but not in \"\\n\", \"\\&\" or \"\\fB\"\n\t$text =~ s/\\\\(?!n|f[A-Z]|&)/\\\\\\\\/g;\n\t# escape \"-\"\n\t$text =~ s/-/\\\\-/g;\n\t# handle ...\n\t$text =~ s/(\\.\\.\\.)/\\\\&\\1/g;\n\t# remove double space after full stop or comma\n\t$text =~ s/([\\.,])  /\\1 /g;\n\n\tif ($option ne 'no-markup') {\n\t\t# make 'italic'\n\t\t$text =~ s/'([^'\\n]*)'/\\\\fI\\1\\\\fR/g;\n\t\t# ignore `\n\t\t$text =~ s/`//g;\n\t\t# make *bold*\n\t\t$text =~ s/\\*([^\\*\\n]*)\\*/\\\\fB\\1\\\\fR/g;\n\t\t# handle <<sections>\n\t\t$text =~ s/<<([^>]*)>>/the section called \\\\(lq\\1\\\\(rq/g;\n\t}\n\n\treturn $text;\n}\n\nsub normal {\n\tmy ($self, $text) = @_;\n\n\tif ($text eq \"\") {\n\t\treturn;\n\t}\n\n\t$text = $self->common($text);\n\n\t$text =~ s/ *\\n(.)/ \\1/g;\n\n\tif ($self->{last_op} eq 'normal') {\n\t\tprint \"\\n\";\n\t}\n\n\tprint $text;\n\n\t$self->{last_op} = 'normal';\n}\n\nsub verse {\n\tmy ($self, $text) = @_;\n\n\t$text = $self->common($text);\n\t$text =~ s/^\\t/        /mg;\n\n\tprint \".sp\\n.RS 4\\n.nf\\n\" . $text . \".fi\\n.RE\\n\";\n\n\t$self->{last_op} = 'verse';\n}\n\nsub enumeration {\n\tmy ($self, $text, $option) = @_;\n\n\tmy $counter = 0;\n\tforeach $line (@$text) {\n\t\t$counter++;\n\t\tprint \".TP 4\\n\"\n\t\t\t. ($option eq 'unnumbered' ? '\\(bu' : $counter . '.')\n\t\t\t. \"\\n\"\n\t\t\t. $self->common($line);\n\t}\n\n\t$self->{last_op} = 'enumeration';\n}\n\nsub begin_item {\n\tmy ($self, $item, $text) = @_;\n\n\t$item = $self->common($item);\n\t$text = $self->common($text);\n\n\t$text =~ s/([^\\n]) *\\n([^\\n])/\\1 \\2/g;\n\n\tprint \".PP\\n\" . $item . \"\\n.RS 4\\n\" . $text;\n\n\t$self->{last_op} = 'item'; \n}\n\nsub end_item {\n\tmy ($self) = @_;\n\n\tprint \".RE\\n\";\n\n\t$self->{last_op} = 'end_item';\n}\n\nsub indent {\n\tmy ($self, $text) = @_;\n\n\t$text = $self->common($text, 'no-markup');\n\t$text =~ s/^\\t/        /mg;\n\n\tif ($self->{last_op} eq 'normal') {\n\t\tprint \"\\n\";\n\t}\n\n\tprint \".sp\\n.RS 4\\n.nf\\n\" . $text . \".fi\\n.RE\\n\";\n\n\t$self->{last_op} = 'indent';\n}\n\nsub verbatim {\n\tmy ($self, $text) = @_;\n\n\t$text = $self->common($text, 'no-markup');\n\n\t# convert tabs to spaces\n\t$text =~ s/^\\t/        /mg;\n\t# remove trailing empty lines\n\t$text =~ s/\\n\\n*$/\\n/;\n\n\tif ($self->{last_op} eq 'normal') {\n\t\tprint \"\\n\";\n\t}\n\n\tprint \".sp\\n.RS 4\\n.nf\\n.ft C\\n\" . $text . \".ft\\n\\n.fi\\n.RE\\n\";\n\n\t$self->{last_op} = 'verbatim';\n}\n\nsub anchor {\n\tmy ($self, $text) = @_;\n\n\t$self->{last_op} = 'anchor';\n}\n\nsub finish {\n\tmy ($self) = @_;\n\tmy $links = $self->{links};\n\n\tif ($#$links >= 0) {\n\t\tprint '.SH \"REFERENCES\"' . \"\\n\";\n\t\tmy $i = 1;\n\t\twhile ($#$links >= 0) {\n\t\t\tmy $ref = shift(@$links);\n\t\t\t$ref =~ s/-/\\\\-/g;\n\t\t\tmy $label = shift(@$links);\n\t\t\tprintf (\".IP \\\"% 2d.\\\" 4\\n%s\\n.RS 4\\n\\\\%%%s\\n.RE\\n\",\n\t\t\t\t$i++, $label, $ref);\n\t\t}\n\t} else {\n\t\tprint \"\\n\";\n\t}\n}\n\npackage html_page;\n\nsub new {\n\tmy ($class) = @_;\n\tmy $self = {};\n\tbless $self, $class;\n\treturn $self;\n}\n\n-- snap --\n\nCiao,\nDscho\n\nP.S.: I need to catch some Zs, and do some real work, so do not be \nsurprised if I do not respond within the next 24 hours.\n"},{"id":"54639","messageId":"4702F6BB.60908@vilain.net","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710030133020.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"Sam Vilain","fromEmail":"sam@vilain.net","sentAt":"2007-10-03T01:56:11Z","receivedAt":"2007-10-03T01:56:11Z","isPatch":false,"sender":{"key":"sam@vilain.net","avatar":"https://gravatar.com/avatar/8fc840ca854dbf6f7065b4335e3b934951c1dca3b11db688e95e471901f8f4a8?d=mp&s=160"},"body":"Johannes Schindelin wrote:\n> Hi,\n> \n> I do not want to depend on more than necessary in msysGit, and therefore I \n> started to write an asciidoc replacement.\n> \n> So here it is: a perl script that does a good job on many .txt files in \n> Documentation/, although for some it deviates from \"make man\"'s output, \n> and for others it is outright broken.  It is meant to be run in \n> Documentation/.\n> \n> My intention is not to fix the script for all cases, but to make patches \n> to Documentation/*.txt themselves, so that they are more consistent (and \n> incidentally nicer to the script).\n> \n> Now, I hear you already moan: \"But Dscho, you know you suck at Perl!\"\n> \n> Yeah, I know, but maybe instead of bashing on me (pun intended), you may \n> want to enlighten me with tips how to make it nicer to read.  (Yes, there \n> are no comments; yes, I will gladly add them where appropriate; yes, html \n> is just a stub.)\n> \n> So here, without further ado, da script:\n\nIt's pretty good, I certainly wouldn't have trouble reading or\nmaintaining it, but I'll give you suggestions anyway.\n\nnice work, replacing a massive XML/XSL/etc stack with a small Perl\nscript ;-)\n\nSam.\n\n> \n> -- snip --\n> #!/usr/bin/perl\n\nAdd -w for warnings, also use strict;\n\n> $conv = new man_page();\n> $conv->{manual} = 'Git Manual';\n> $conv->{git_version} = 'Git ' . `cat ../GIT-VERSION-FILE`;\n> $conv->{git_version} =~ s/GIT_VERSION = //;\n> $conv->{git_version} =~ s/-/\\\\-/;\n> $conv->{git_version} =~ s/\\n//;\n> $conv->{date} = `date +%m/%d/%Y`;\n> $conv->{date} =~ s/\\n//;\n> \n> $par = '';\n> handle_file($ARGV[0]);\n> $conv->finish();\n> \n> sub handle_text {\n\nthis function acts on globals; make them explicit arguments to the function.\n\n> \tif ($par =~ /^\\. /s) {\n> \t\tmy @lines = split(/^\\. /m, $par);\n> \t\tshift @lines;\n> \t\t$conv->enumeration(\\@lines);\n> \t} elsif ($par =~ /^\\* /s) {\n\nuncuddle your elsif's; also consider making this a \"tabular ternary\"\nwith the actions in separate functions.\n\nie\n\n$result = ( $par =~ /^\\. /s      ? $conv->do_enum($par)    :\n            $par =~ /^\\[verse\\]/ ? $conv->do_verse($par)  :\n            ... )\n\nHowever I have a suspicion that your script is doing line-based parsing\ninstead of recursive descent; I don't know whether that's the right\nthing for asciidoc.  It's actually fairly easy to convert a grammar to\ncode blocks using tricks from MJD's _Higher Order Perl_.  Is it\nnecessary for the asciidoc grammar?\n\n> \t\tmy @lines = split(/^\\* /m, $par);\n> \t\tshift @lines;\n> \t\t$conv->enumeration(\\@lines, 'unnumbered');\n> \t} elsif ($par =~ /^\\[verse\\]/) {\n> \t\t$par =~ s/\\[verse\\] *\\n?//;\n> \t\t$conv->verse($par);\n> \t} elsif ($par =~ /^(\\t|  +)/s) {\n> \t\t$par =~ s/^$1//mg;\n> \t\t$par =~ s/^\\+$//mg;\n> \t\t$conv->indent($par);\n> \t} elsif ($par =~ /^([^\\n]*)::\\n((\\t|  +).*)$/s) {\n> \t\tmy ($first, $rest, $indent) = ($1, $2, $3);\n> \t\t$rest =~ s/^\\+$//mg;\n> \t\twhile ($rest =~ /^(.*?\\n\\n)--+\\n(.*?\\n)--+\\n\\n(.*)$/s) {\n> \t\t\tmy ($pre, $verb, $post) = ($1, $2, $3);\n> \n> \t\t\t$pre =~ s/^(\\t|$indent)//mg;\n> \t\t\tif ($first ne '') {\n> \t\t\t\t$conv->begin_item($first, $pre);\n> \t\t\t\t$first = '';\n> \t\t\t} else {\n> \t\t\t\t$conv->normal($pre);\n> \t\t\t}\n> \n> \t\t\t$conv->verbatim($verb);\n> \t\t\t$rest = $post;\n> \t\t}\n> \t\t$rest =~ s/^(\\t|$indent)//mg;\n> \t\tif ($first ne '') {\n> \t\t\t$conv->begin_item($first, $rest);\n> \t\t} else {\n> \t\t\t$conv->normal($rest);\n> \t\t}\n> \t\t$conv->end_item();\n> \t} elsif ($par =~ /^-+\\n(.*\\n)-+\\n$/s) {\n> \t\t$conv->verbatim($1);\n> \t} else {\n> \t\t$conv->normal($par);\n> \t}\n> \t$par = '';\n> }\n> \n> sub handle_file {\n> \tmy $in;\n> \topen($in, '<' . $_[0]);\n> \twhile (<$in>) {\n> \t\tif (/^=+$/) {\n> \t\t\tif ($par ne '' && length($_) >= length($par)) {\n> \t\t\t\t$conv->header($par);\n> \t\t\t\t$par = '';\n> \t\t\t\tnext;\n> \t\t\t}\n> \t\t} elsif (/^-+$/) {\n> \t\t\tif ($par ne '' && length($_) >= length($par)) {\n> \t\t\t\t$conv->section($par);\n> \t\t\t\t$par = '';\n> \t\t\t\tnext;\n> \t\t\t}\n> \t\t} elsif (/^~+$/) {\n> \t\t\tif ($par ne '' && length($_) >= length($par)) {\n> \t\t\t\t$conv->subsection($par);\n> \t\t\t\t$par = '';\n> \t\t\t\tnext;\n> \t\t\t}\n> \t\t} elsif (/^\\[\\[(.*)\\]\\]$/) {\n> \t\t\thandle_text();\n> \t\t\t$conv->anchor($1);\n> \t\t\tnext;\n> \t\t} elsif (/^$/) {\n> \t\t\tif ($par =~ /^-+\\n.*[^-]\\n$/s) {\n> \t\t\t\t# fallthru; is verbatim, but needs more.\n> \t\t\t} elsif ($par =~ /::\\n$/s) {\n> \t\t\t\t# is item, but needs more.\n> \t\t\t\tnext;\n> \t\t\t} else {\n> \t\t\t\thandle_text();\n> \t\t\t\tnext;\n> \t\t\t}\n> \t\t} elsif (/^include::(.*)\\[\\]$/) {\n> \t\t\thandle_text();\n> \t\t\thandle_file($1);\n> \t\t\tnext;\n> \t\t}\n> \n> \t\t# convert \"\\--\" to \"--\"\n> \t\ts/\\\\--/--/g;\n> \t\t# convert \"\\*\" to \"*\"\n> \t\ts/\\\\\\*/*/g;\n> \n> \t\t# handle gitlink:\n> \t\ts/gitlink:([^\\[ ]*)\\[(\\d+)\\]/sprintf \"%s\",\n> \t\t\t$conv->get_link($1, $2)/ge;\n> \t\t# handle link:\n> \t\ts/link:([^\\[ ]*)\\[(.+)\\]/sprintf \"%s\",\n> \t\t\t$conv->get_link($1, $2, 'external')/ge;\n\nThese REs suffer from LTS (Leaning Toothpick Syndrome).  Consider using\ns{foo}{bar} and adding the 'x' modifier to space out groups.\n\n> \n> \t\t$par .= $_;\n> \t}\n> \tclose($in);\n> \thandle_text();\n> }\n> \n> package man_page;\n> \n> sub new {\n> \tmy ($class) = @_;\n> \tmy $self = {\n> \t\tsep => '',\n> \t\tlinks => [],\n> #\t\tgenerator => 'Home grown git txt2man converter'\n> \t\tgenerator => 'DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>'\n> \t};\n> \tbless $self, $class;\n> \treturn $self;\n> }\n> \n> sub header {\n> \tmy ($self, $text) = @_;\n> \t$text =~ s/-/\\\\-/g;\n> \n> \tif ($self->{preamble_shown} == undef) {\n> \t\t$title = $text;\n> \t\t$title =~ s/\\(\\d+\\)$//;\n> \t\tprint '.\\\"     Title: ' . $title\n> \t\t\t. '.\\\"    Author: ' . \"\\n\"\n> \t\t\t. '.\\\" Generator: ' . $self->{generator} . \"\\n\"\n> \t\t\t. '.\\\"      Date: ' . $self->{date} . \"\\n\"\n> \t\t\t. '.\\\"    Manual: ' . $self->{manual} . \"\\n\"\n> \t\t\t. '.\\\"    Source: ' . $self->{git_version} . \"\\n\"\n> \t\t\t. '.\\\"' . \"\\n\";\n> \t}\n\nI'd consider a HERE-doc, or multi-line qq{ } more readable than this.\n\n> \n> \t$text =~ tr/a-z/A-Z/;\n> \tmy $suffix = \"\\\"$self->{date}\\\" \\\"$self->{git_version}\\\"\"\n> \t\t. \" \\\"$self->{manual}\\\"\";\n\nUse qq{} when making strings with lots of embedded double quotes and\ninterpolation.\n\n> \t$text =~ s/^(.*)\\((\\d+)\\)$/.TH \"\\1\" \"\\2\" $suffix/;\n> \tprint $text;\n> \n> \tif ($self->{preamble_shown} == undef) {\n> \t\tprint '.\\\" disable hyphenation' . \"\\n\"\n> \t\t\t. '.nh' . \"\\n\"\n> \t\t\t. '.\\\" disable justification (adjust text to left'\n> \t\t\t\t. ' margin only)' . \"\\n\"\n> \t\t\t. '.ad l' . \"\\n\";\n\nUsing commas rather than \".\" will safe you a concat when printing to\nfilehandles, but that's a very small nit to pick :)\n\n> \t\t$self->{preamble_shown} = 1;\n> \t}\n> \n> \t$self->{last_op} = 'header';\n> }\n> \n> sub section {\n> \tmy ($self, $text) = @_;\n> \n> \t$text =~ tr/a-z/A-Z/;\n> \t$text =~ s/^(.*)$/.SH \"\\1\"/;\n> \n> \tprint $text;\n> \n> \t$self->{last_op} = 'section';\n> }\n> \n> sub subsection {\n> \tmy ($self, $text) = @_;\n> \n> \t$text =~ s/^(.*)$/.SS \"\\1\"/;\n> \n> \tprint $text;\n> \n> \t$self->{last_op} = 'subsection';\n> }\n> \n> sub get_link {\n> \tmy ($self, $command, $section, $option) = @_;\n> \n> \tif ($option eq 'external') {\n> \t\tmy $links = $self->{links};\n> \t\tpush(@$links, $command);\n> \t\t$command =~ s/\\.html$//;\n> \t\t$command =~ s/-/ /g;\n> \t\tpush(@$links, $command);\n> \t\treturn '\\fI' . $command . '\\fR\\&[1]';\n> \t} else {\n> \t\treturn '\\fB' . $command . '\\fR(' . $section . ')';\n> \t}\n> }\n> \n> sub common {\n> \tmy ($self, $text, $option) = @_;\n> \n> \t# escape backslashes, but not in \"\\n\", \"\\&\" or \"\\fB\"\n> \t$text =~ s/\\\\(?!n|f[A-Z]|&)/\\\\\\\\/g;\n> \t# escape \"-\"\n> \t$text =~ s/-/\\\\-/g;\n> \t# handle ...\n> \t$text =~ s/(\\.\\.\\.)/\\\\&\\1/g;\n> \t# remove double space after full stop or comma\n> \t$text =~ s/([\\.,])  /\\1 /g;\n> \n> \tif ($option ne 'no-markup') {\n> \t\t# make 'italic'\n> \t\t$text =~ s/'([^'\\n]*)'/\\\\fI\\1\\\\fR/g;\n> \t\t# ignore `\n> \t\t$text =~ s/`//g;\n> \t\t# make *bold*\n> \t\t$text =~ s/\\*([^\\*\\n]*)\\*/\\\\fB\\1\\\\fR/g;\n> \t\t# handle <<sections>\n> \t\t$text =~ s/<<([^>]*)>>/the section called \\\\(lq\\1\\\\(rq/g;\n\nHmm, that regex would not match for <<foo > bar>>, if you care you'd\nneed to write something like <<((?:[^>]+|>[^>])*)>>\n\n> \t}\n> \n> \treturn $text;\n> }\n> \n> sub normal {\n> \tmy ($self, $text) = @_;\n> \n> \tif ($text eq \"\") {\n> \t\treturn;\n> \t}\n> \n> \t$text = $self->common($text);\n> \n> \t$text =~ s/ *\\n(.)/ \\1/g;\n> \n> \tif ($self->{last_op} eq 'normal') {\n> \t\tprint \"\\n\";\n> \t}\n> \n> \tprint $text;\n> \n> \t$self->{last_op} = 'normal';\n> }\n> \n> sub verse {\n> \tmy ($self, $text) = @_;\n> \n> \t$text = $self->common($text);\n> \t$text =~ s/^\\t/        /mg;\n> \n> \tprint \".sp\\n.RS 4\\n.nf\\n\" . $text . \".fi\\n.RE\\n\";\n> \n> \t$self->{last_op} = 'verse';\n> }\n> \n> sub enumeration {\n> \tmy ($self, $text, $option) = @_;\n> \n> \tmy $counter = 0;\n> \tforeach $line (@$text) {\n> \t\t$counter++;\n> \t\tprint \".TP 4\\n\"\n> \t\t\t. ($option eq 'unnumbered' ? '\\(bu' : $counter . '.')\n> \t\t\t. \"\\n\"\n> \t\t\t. $self->common($line);\n> \t}\n> \n> \t$self->{last_op} = 'enumeration';\n> }\n> \n> sub begin_item {\n> \tmy ($self, $item, $text) = @_;\n> \n> \t$item = $self->common($item);\n> \t$text = $self->common($text);\n> \n> \t$text =~ s/([^\\n]) *\\n([^\\n])/\\1 \\2/g;\n\n\".\" is the same as [^\\n] (without the 's' modifier).\n\n> \n> \tprint \".PP\\n\" . $item . \"\\n.RS 4\\n\" . $text;\n> \n> \t$self->{last_op} = 'item'; \n> }\n> \n> sub end_item {\n> \tmy ($self) = @_;\n> \n> \tprint \".RE\\n\";\n> \n> \t$self->{last_op} = 'end_item';\n> }\n> \n> sub indent {\n> \tmy ($self, $text) = @_;\n> \n> \t$text = $self->common($text, 'no-markup');\n> \t$text =~ s/^\\t/        /mg;\n> \n> \tif ($self->{last_op} eq 'normal') {\n> \t\tprint \"\\n\";\n> \t}\n> \n> \tprint \".sp\\n.RS 4\\n.nf\\n\" . $text . \".fi\\n.RE\\n\";\n> \n> \t$self->{last_op} = 'indent';\n> }\n> \n> sub verbatim {\n> \tmy ($self, $text) = @_;\n> \n> \t$text = $self->common($text, 'no-markup');\n> \n> \t# convert tabs to spaces\n> \t$text =~ s/^\\t/        /mg;\n> \t# remove trailing empty lines\n> \t$text =~ s/\\n\\n*$/\\n/;\n> \n> \tif ($self->{last_op} eq 'normal') {\n> \t\tprint \"\\n\";\n> \t}\n> \n> \tprint \".sp\\n.RS 4\\n.nf\\n.ft C\\n\" . $text . \".ft\\n\\n.fi\\n.RE\\n\";\n> \n> \t$self->{last_op} = 'verbatim';\n> }\n> \n> sub anchor {\n> \tmy ($self, $text) = @_;\n> \n> \t$self->{last_op} = 'anchor';\n> }\n> \n> sub finish {\n> \tmy ($self) = @_;\n> \tmy $links = $self->{links};\n> \n> \tif ($#$links >= 0) {\n> \t\tprint '.SH \"REFERENCES\"' . \"\\n\";\n> \t\tmy $i = 1;\n> \t\twhile ($#$links >= 0) {\n\njust use if (@$links) and while (@$links)\n\n> \t\t\tmy $ref = shift(@$links);\n> \t\t\t$ref =~ s/-/\\\\-/g;\n> \t\t\tmy $label = shift(@$links);\n> \t\t\tprintf (\".IP \\\"% 2d.\\\" 4\\n%s\\n.RS 4\\n\\\\%%%s\\n.RE\\n\",\n> \t\t\t\t$i++, $label, $ref);\n> \t\t}\n> \t} else {\n> \t\tprint \"\\n\";\n> \t}\n> }\n> \n> package html_page;\n> \n> sub new {\n> \tmy ($class) = @_;\n> \tmy $self = {};\n> \tbless $self, $class;\n> \treturn $self;\n> }\n> \n> -- snap --\n> \n> Ciao,\n> Dscho\n> \n> P.S.: I need to catch some Zs, and do some real work, so do not be \n> surprised if I do not respond within the next 24 hours.\n> -\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n"},{"id":"54649","messageId":"Pine.LNX.4.64.0710030506360.28395@racer.site","threadId":"10121","inReplyTo":"4702F6BB.60908@vilain.net","subject":"Re: WIP: asciidoc replacement","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-10-03T04:23:35Z","receivedAt":"2007-10-03T04:23:35Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 3 Oct 2007, Sam Vilain wrote:\n\n> Johannes Schindelin wrote:\n> \n> > I do not want to depend on more than necessary in msysGit, and \n> > therefore I started to write an asciidoc replacement.\n> \n> It's pretty good, I certainly wouldn't have trouble reading or \n> maintaining it, but I'll give you suggestions anyway.\n\nThank you very much!  (On both accounts...)\n\n> nice work, replacing a massive XML/XSL/etc stack with a small Perl \n> script ;-)\n\nUhm... It is less capable, though...\n\n> > -- snip --\n> > #!/usr/bin/perl\n> \n> Add -w for warnings, also use strict;\n\n<dumb>What does \"use strict;\" imply?</dumb>\n\n> > sub handle_text {\n> \n> this function acts on globals; make them explicit arguments to the \n> function.\n\nActually, it resets the global $par.  Should I rather make it a class?\n\n> > \tif ($par =~ /^\\. /s) {\n> > \t\tmy @lines = split(/^\\. /m, $par);\n> > \t\tshift @lines;\n> > \t\t$conv->enumeration(\\@lines);\n> > \t} elsif ($par =~ /^\\* /s) {\n> \n> uncuddle your elsif's;\n\nI'm sorry... What do you mean?\n\n> also consider making this a \"tabular ternary\" with the actions in \n> separate functions.\n> \n> ie\n> \n> $result = ( $par =~ /^\\. /s      ? $conv->do_enum($par)    :\n>             $par =~ /^\\[verse\\]/ ? $conv->do_verse($par)  :\n>             ... )\n\nI do not like that way... is it Perl standard to code like that?\n\n> However I have a suspicion that your script is doing line-based parsing \n> instead of recursive descent; I don't know whether that's the right \n> thing for asciidoc.  It's actually fairly easy to convert a grammar to \n> code blocks using tricks from MJD's _Higher Order Perl_.  Is it \n> necessary for the asciidoc grammar?\n\nI wanted to keep it simple.  So I'll try to stay away from any fancy \ngrammar parsing, and stay with \"read lines until you have something to \nprocess\".\n\n> > \t\t# handle gitlink:\n> > \t\ts/gitlink:([^\\[ ]*)\\[(\\d+)\\]/sprintf \"%s\",\n> > \t\t\t$conv->get_link($1, $2)/ge;\n> > \t\t# handle link:\n> > \t\ts/link:([^\\[ ]*)\\[(.+)\\]/sprintf \"%s\",\n> > \t\t\t$conv->get_link($1, $2, 'external')/ge;\n> \n> These REs suffer from LTS (Leaning Toothpick Syndrome).  Consider using \n> s{foo}{bar} and adding the 'x' modifier to space out groups.\n\nI guess you mean the forward slash.  Alas, that's what I'm used to, and \nI'd rather not change it unless forced to... lest I stop understanding my \nown code!\n\n(Besides, I did not find _any_ example showing why \"x\" should be useful.)\n\n> > \tif ($self->{preamble_shown} == undef) {\n> > \t\t$title = $text;\n> > \t\t$title =~ s/\\(\\d+\\)$//;\n> > \t\tprint '.\\\"     Title: ' . $title\n> > \t\t\t. '.\\\"    Author: ' . \"\\n\"\n> > \t\t\t. '.\\\" Generator: ' . $self->{generator} . \"\\n\"\n> > \t\t\t. '.\\\"      Date: ' . $self->{date} . \"\\n\"\n> > \t\t\t. '.\\\"    Manual: ' . $self->{manual} . \"\\n\"\n> > \t\t\t. '.\\\"    Source: ' . $self->{git_version} . \"\\n\"\n> > \t\t\t. '.\\\"' . \"\\n\";\n> > \t}\n> \n> I'd consider a HERE-doc, or multi-line qq{ } more readable than this.\n\nCan you give me an example of a HERE-doc?  (What I tried to avoid is \nhaving ugly indentation-breaking tlobs.)\n\n> > \t$text =~ tr/a-z/A-Z/;\n> > \tmy $suffix = \"\\\"$self->{date}\\\" \\\"$self->{git_version}\\\"\"\n> > \t\t. \" \\\"$self->{manual}\\\"\";\n> \n> Use qq{} when making strings with lots of embedded double quotes and\n> interpolation.\n\nI'll try to find something about qq{} in the docs.\n\n> > \t$text =~ s/^(.*)\\((\\d+)\\)$/.TH \"\\1\" \"\\2\" $suffix/;\n> > \tprint $text;\n> > \n> > \tif ($self->{preamble_shown} == undef) {\n> > \t\tprint '.\\\" disable hyphenation' . \"\\n\"\n> > \t\t\t. '.nh' . \"\\n\"\n> > \t\t\t. '.\\\" disable justification (adjust text to left'\n> > \t\t\t\t. ' margin only)' . \"\\n\"\n> > \t\t\t. '.ad l' . \"\\n\";\n> \n> Using commas rather than \".\" will safe you a concat when printing to\n> filehandles, but that's a very small nit to pick :)\n\nDoes that also work with older perl?  IIRC there was some strange problem \nwith my perl when lots of code in git.git was changed to using commata.\n\n> > \t\t# handle <<sections>\n> > \t\t$text =~ s/<<([^>]*)>>/the section called \\\\(lq\\1\\\\(rq/g;\n> \n> Hmm, that regex would not match for <<foo > bar>>, if you care you'd \n> need to write something like <<((?:[^>]+|>[^>])*)>>\n\nI'd rather leave it as is -- this script is not meant to grok all kind of \nsh*t.  It is meant to make translating the docs as fast and uncumbersome \nas possible.  Which will involve making the documentation more consistent \n(in and of itself something I rather like).\n\nSo unless there comes a compelling reason, I'd rather leave it.\n\n> > sub begin_item {\n> > \tmy ($self, $item, $text) = @_;\n> > \n> > \t$item = $self->common($item);\n> > \t$text = $self->common($text);\n> > \n> > \t$text =~ s/([^\\n]) *\\n([^\\n])/\\1 \\2/g;\n> \n> \".\" is the same as [^\\n] (without the 's' modifier).\n\nBut I need the (implicit) 's' modifier, otherwise the \"\\n\" in the middle \nis not interpreted correctly.  This regsub is meant to unwrap the \nparagraph and put it into a very long line (but leaving \\n\\n alone).\n\n> > sub finish {\n> > \tmy ($self) = @_;\n> > \tmy $links = $self->{links};\n> > \n> > \tif ($#$links >= 0) {\n> > \t\tprint '.SH \"REFERENCES\"' . \"\\n\";\n> > \t\tmy $i = 1;\n> > \t\twhile ($#$links >= 0) {\n> \n> just use if (@$links) and while (@$links)\n\nThanks.  I hoped there would be something like this.\n\nAnother thing: if I want to add some documentation, what would be the \ncommon way to do it?  =pod...=cut?\n\nThank you for all your tips!\n\nCiao,\nDscho\n"},{"id":"54652","messageId":"7vprzwhkgd.fsf@gitster.siamese.dyndns.org","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710030133020.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-10-03T04:48:50Z","receivedAt":"2007-10-03T04:48:50Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> So here it is: a perl script that does a good job on many .txt files in \n> Documentation/, although for some it deviates from \"make man\"'s output, \n> and for others it is outright broken.  It is meant to be run in \n> Documentation/.\n>\n> My intention is not to fix the script for all cases, but to make patches \n> to Documentation/*.txt themselves, so that they are more consistent (and \n> incidentally nicer to the script).\n\nHow you spend your time is up to you, but I need to wonder...\n\n - Is \"man\" format important for msysGit aka Windows\n   environment?  I had an impression that their helpfile format\n   were closer to \"html\" output.\n\n - Does it make sense in the longer term for us to maintain\n   in-house documentation tools?  Can we afford it?\n\nIt appears that we heard about breakages for every minor docbook\nupdates, and it is really appealing if we do not have to rely on\nxsl toolchain for manpage generation.  But if patching the text\nmeans making it compatible with the in-house script _and_\nincompatible with AsciiDoc, hmmm...\n"},{"id":"54653","messageId":"20071003045148.GD11905@coredump.intra.peff.net","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710030506360.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2007-10-03T04:51:48Z","receivedAt":"2007-10-03T04:51:48Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 03, 2007 at 05:23:35AM +0100, Johannes Schindelin wrote:\n\n> > > #!/usr/bin/perl\n> > \n> > Add -w for warnings, also use strict;\n> \n> <dumb>What does \"use strict;\" imply?</dumb>\n\nTry \"perldoc strict\" for details.\n\n> > > \tif ($par =~ /^\\. /s) {\n> > > \t\tmy @lines = split(/^\\. /m, $par);\n> > > \t\tshift @lines;\n> > > \t\t$conv->enumeration(\\@lines);\n> > > \t} elsif ($par =~ /^\\* /s) {\n> > \n> > uncuddle your elsif's;\n> \n> I'm sorry... What do you mean?\n\nI think he means reformatting to\n\n  if (condition) {\n  }\n  elsif (condition) {\n  }\n\n> > $result = ( $par =~ /^\\. /s      ? $conv->do_enum($par)    :\n> >             $par =~ /^\\[verse\\]/ ? $conv->do_verse($par)  :\n> >             ... )\n> \n> I do not like that way... is it Perl standard to code like that?\n\nIt's quite common if you have a dispatch function, but obviously not\nrequired.\n\n> > > \t\t$title =~ s/\\(\\d+\\)$//;\n> > > \t\tprint '.\\\"     Title: ' . $title\n> > > \t\t\t. '.\\\"    Author: ' . \"\\n\"\n> > > \t\t\t. '.\\\" Generator: ' . $self->{generator} . \"\\n\"\n> > > \t\t\t. '.\\\"      Date: ' . $self->{date} . \"\\n\"\n> > > \t\t\t. '.\\\"    Manual: ' . $self->{manual} . \"\\n\"\n> > > \t\t\t. '.\\\"    Source: ' . $self->{git_version} . \"\\n\"\n> > > \t\t\t. '.\\\"' . \"\\n\";\n> > > \t}\n> > \n> > I'd consider a HERE-doc, or multi-line qq{ } more readable than this.\n> \n> Can you give me an example of a HERE-doc?  (What I tried to avoid is \n> having ugly indentation-breaking tlobs.)\n\nprint <<EOF;\nfoo\nEOF\n\nHERE-docs necessarily break indentation unless you strip it out manually\n(which is inefficient and ugly).\n\nBut two things that might make that look better are using qq// (to avoid\nhaving to escape quotes) and interpolating the variables:\n\n  . qq/.\" Generator: $self->{generator}\\n/\n\n> I'll try to find something about qq{} in the docs.\n\nIt's in perlop, but it's basically a fancy way of double-quoting, except\nthat you get to choose the delimiter.\n\n> > > \t$text =~ s/([^\\n]) *\\n([^\\n])/\\1 \\2/g;\n> > \n> > \".\" is the same as [^\\n] (without the 's' modifier).\n> \n> But I need the (implicit) 's' modifier, otherwise the \"\\n\" in the middle \n> is not interpreted correctly.  This regsub is meant to unwrap the \n> paragraph and put it into a very long line (but leaving \\n\\n alone).\n\nI think you might be confused about how the 's' modifier works. You are\nnot using it, so '.' is the same as '[^\\n]'. Perl will always match a\nnewline if it's in your regex. If you specify 'm', then it will also\nallow '^' and '$' to match at line boundaries (instead of just at the\nbeginning and end of the string).\n\n-Peff\n"},{"id":"54668","messageId":"39F3EE1B-7BD4-4927-AB90-2EB4BBAF05D0@wincent.com","threadId":"10121","inReplyTo":"7vprzwhkgd.fsf@gitster.siamese.dyndns.org","subject":"Re: WIP: asciidoc replacement","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-10-03T06:34:25Z","receivedAt":"2007-10-03T06:34:25Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 3/10/2007, a las 6:48, Junio C Hamano escribió:\n\n>  - Does it make sense in the longer term for us to maintain\n>    in-house documentation tools?  Can we afford it?\n>\n> It appears that we heard about breakages for every minor docbook\n> updates, and it is really appealing if we do not have to rely on\n> xsl toolchain for manpage generation.\n\nIndeed, especially seeing as asciidoc and the xsl toolchain are the  \ntrickiest build dependencies to install. If all that could be  \nreplaced by a single simple script like this one then that would be  \nawesome, and probably more maintainable in the long run seeing as it  \nwould eliminate those intermittent breakages caused by changes in  \nthird-party tools.\n\nCheers,\nWincent\n"},{"id":"54665","messageId":"06B9DBA8-596F-4576-8995-8044EA714384@wincent.com","threadId":"10121","inReplyTo":"4702F6BB.60908@vilain.net","subject":"Re: WIP: asciidoc replacement","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-10-03T06:40:06Z","receivedAt":"2007-10-03T06:40:06Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 3/10/2007, a las 3:56, Sam Vilain escribió:\n\n> However I have a suspicion that your script is doing line-based  \n> parsing\n> instead of recursive descent; I don't know whether that's the right\n> thing for asciidoc.  It's actually fairly easy to convert a grammar to\n> code blocks using tricks from MJD's _Higher Order Perl_.  Is it\n> necessary for the asciidoc grammar?\n\nI haven't looked at all of the asciidoc source for the Git  \ndocumentation but I suspect that almost all of it is entirely  \nregular, and if there is any nesting in it is is probably of a  \nlimited scope (ie. sections, subsections, subsubsections in the user  \nmanual) and so you can avoid the complexity of a full recursive  \ndescent parser. I'd also expect Johannes' approach to be faster (is  \nit faster than the existing tool chain? I would expect so).\n\nCheers,\nWincent\n"},{"id":"54678","messageId":"85abr0y5ua.fsf@lola.goethe.zz","threadId":"10121","inReplyTo":"39F3EE1B-7BD4-4927-AB90-2EB4BBAF05D0@wincent.com","subject":"Re: WIP: asciidoc replacement","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-10-03T08:12:29Z","receivedAt":"2007-10-03T08:12:29Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Wincent Colaiuta <win@wincent.com> writes:\n\n> El 3/10/2007, a las 6:48, Junio C Hamano escribió:\n>\n>>  - Does it make sense in the longer term for us to maintain\n>>    in-house documentation tools?  Can we afford it?\n>>\n>> It appears that we heard about breakages for every minor docbook\n>> updates, and it is really appealing if we do not have to rely on\n>> xsl toolchain for manpage generation.\n>\n> Indeed, especially seeing as asciidoc and the xsl toolchain are the  \n> trickiest build dependencies to install. If all that could be  \n> replaced by a single simple script like this one then that would be  \n> awesome, and probably more maintainable in the long run seeing as it  \n> would eliminate those intermittent breakages caused by changes in  \n> third-party tools.\n\nWhat with output in print, HTML, info?  The advantage of a toolchain\nin that it is flexible.  I am the first to admit that getting the\nAsciiDoc/Docbook/Docbook2X toolchain to get it to do what one wants to\nis like baking cake in a lightless kitchen.  But it is not like we go\nthrough that pain without any reason.\n\nPersonally, I think it might make sense to just step away from the\nAsciiDoc documentation to Docbook: plain text (without cutified\nformatting control like in AsciiDoc) can be generated _from_ Docbook.\n\nAnd AsciiDoc keeps us from documenting the formatting: Docbook, which\nis a source format and looks it, can easily admit comments that won't\nget through to the formatted versions.  Sure, the first version would\nlikely be generated with AsciiDoc and thus basically uncommented.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"54686","messageId":"1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com","threadId":"10121","inReplyTo":"85abr0y5ua.fsf@lola.goethe.zz","subject":"Re: WIP: asciidoc replacement","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2007-10-03T10:05:29Z","receivedAt":"2007-10-03T10:05:29Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 3/10/2007, a las 10:12, David Kastrup escribió:\n\n> What with output in print, HTML, info?\n\nYes, that's still a problem...\n\n> Personally, I think it might make sense to just step away from the\n> AsciiDoc documentation to Docbook: plain text (without cutified\n> formatting control like in AsciiDoc) can be generated _from_ Docbook.\n\nYes, but editing DocBook (XML) is relatively painful compared to  \nediting plain text. You either have to rely on a bloated XML- \nvalidating editor or instead ask your doc authors to manually write  \nvalid XML (and I totally agree with Terrence Parr that, \"XML makes a  \nlousy human interface\n\"; see <http://www.ibm.com/developerworks/xml/library/x-sbxml.html>  \nfor his full take).\n\nI know that Linus has argued for AsciiDoc because the source *is* the  \nplain text documentation and is therefore easily readable, but for me  \nthe real benefit lies in the fact that *because* the source is plain  \ntext it is easily edited (ie. that the source is easily *writeable*),  \nand things like documentation patches are very neat with AsciiDoc.\n\nCheers,\nWincent\n"},{"id":"54687","messageId":"85k5q4v6jb.fsf@lola.goethe.zz","threadId":"10121","inReplyTo":"1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com","subject":"Re: WIP: asciidoc replacement","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-10-03T10:25:44Z","receivedAt":"2007-10-03T10:25:44Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Wincent Colaiuta <win@wincent.com> writes:\n\n> El 3/10/2007, a las 10:12, David Kastrup escribió:\n>\n>> What with output in print, HTML, info?\n>\n> Yes, that's still a problem...\n>\n>> Personally, I think it might make sense to just step away from the\n>> AsciiDoc documentation to Docbook: plain text (without cutified\n>> formatting control like in AsciiDoc) can be generated _from_ Docbook.\n>\n> Yes, but editing DocBook (XML) is relatively painful compared to\n> editing plain text.\n\nThe problem is that we are not editing plain text, but Docbook source\nmasquerading as plain text.\n\n> You either have to rely on a bloated XML- validating editor or\n> instead ask your doc authors to manually write valid XML (and I\n> totally agree with Terrence Parr that, \"XML makes a lousy human\n> interface \"; see\n> <http://www.ibm.com/developerworks/xml/library/x-sbxml.html> for his\n> full take).\n>\n> I know that Linus has argued for AsciiDoc because the source *is*\n> the plain text documentation and is therefore easily readable, but\n> for me the real benefit lies in the fact that *because* the source\n> is plain text it is easily edited (ie. that the source is easily\n> *writeable*), and things like documentation patches are very neat\n> with AsciiDoc.\n\nBut it is not all _all_ easily writeable the moment you try to do\nsomething with _structural_ impact.  In fact, it is pretty much\nimpossible for anybody except wizards to do that.  And when the\nwizards do it, they can't actually document what they have been doing\nsince that would mean cluttering the purported \"plain text\ndocumentation\" with formatting comments.\n\nMaybe it would help to rename *.txt to *.asciidoc and generate *.txt\nin future.  That would at least make it possible to document stuff in\nthe AsciiDoc source, and also would make it possible to add indexing\ninfo and other stuff without cluttering up the plain text use case.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"54689","messageId":"20071003105221.GA11409@uranus.ravnborg.org","threadId":"10121","inReplyTo":"85k5q4v6jb.fsf@lola.goethe.zz","subject":"Re: WIP: asciidoc replacement","fromName":"Sam Ravnborg","fromEmail":"sam@ravnborg.org","sentAt":"2007-10-03T10:52:21Z","receivedAt":"2007-10-03T10:52:21Z","isPatch":false,"sender":{"key":"sam@ravnborg.org","avatar":"https://gravatar.com/avatar/168a912606ed0742d840bb365e3cc21db390c36531a58341dc7a069cc1f15f62?d=mp&s=160"},"body":"Hi David.\n> \n> But it is not all _all_ easily writeable the moment you try to do\n> something with _structural_ impact.  In fact, it is pretty much\n> impossible for anybody except wizards to do that.  And when the\n> wizards do it, they can't actually document what they have been doing\n> since that would mean cluttering the purported \"plain text\n> documentation\" with formatting comments.\nWhen I converted part of the kbuild documentation to ascii doc\nis was a strightforward excercise.\nThe txt file was equally readable before and after,\nand the generated HTML looks OK.\n\nUp until 3.6 in following link were properly converted:\nhttp://www.ravnborg.org/kbuild/makefiles.html\n\nBut I did not convince asciidoc to generate an index - is it this\nyou refer to as magic?\n\nUsing the kbuild doc as my background I would say that with\nor without asciidoc there were a requirment for a consistent\nstyle used throughout the file.\nAnd that style was and are simple to use just by copying\nrelevant examples.\n\nWhat asciidoc gave me was a simple syntax chack of what I did.\nI found wrong references when playing with asciidoc as\none example.\n\nIf the asciidoc replacement prove a success for git I would\nconsider suggesting it for the kernel too.\nIt would be good to generate some nicer loking online documentation\nand here an asii tool like thing would be a help.\n\n\tSam\n"},{"id":"54691","messageId":"7vd4vwfou9.fsf@gitster.siamese.dyndns.org","threadId":"10121","inReplyTo":"1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com","subject":"Re: WIP: asciidoc replacement","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-10-03T10:57:02Z","receivedAt":"2007-10-03T10:57:02Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta <win@wincent.com> writes:\n\n> Yes, but editing DocBook (XML) is relatively painful compared to  \n> editing plain text. You either have to rely on a bloated XML- \n> validating editor or instead ask your doc authors to manually write  \n> valid XML (and I totally agree with Terrence Parr that, \"XML makes a  \n> lousy human interface\n> \"; see <http://www.ibm.com/developerworks/xml/library/x-sbxml.html>  \n> for his full take).\n>\n> I know that Linus has argued for AsciiDoc because the source *is* the  \n> plain text documentation and is therefore easily readable, but for me  \n> the real benefit lies in the fact that *because* the source is plain  \n> text it is easily edited (ie. that the source is easily *writeable*),  \n> and things like documentation patches are very neat with AsciiDoc.\n\nTo give credits to where they are due, most of the structure of\nthe initial documentation was done during the first week of May\n2005 by David Greaves while Linus was vacationing, and the first\nperson who brought up AsciiDoc was Bert Hubert.\n\n    http://article.gmane.org/gmane.comp.version-control.git/2323\n\nOne thing Linus had to say about the issue from early on, and I\nstill agree with, is the last paragraph in:\n\n    http://article.gmane.org/gmane.comp.version-control.git/2298\n\nThere was another thread in the recent past\n\n    http://article.gmane.org/gmane.comp.version-control.git/55059\n\nI've seen markdown used elsewhere, and I regularly read pod.\nThese are both used by other people (I _care_ about good\nexternal support and user community), are readable as straight\ntext (I personally care more about this than prettyprinted\noutput), and can be alternative candidates if we consider\nswitching.\n\nHow good are HTML and manpage output support from these (or\nother candidates) formats these days?  Output to help page\nformat Windows folks use (I am assuming Mac people are happy as\nlong as man is available) would be a definite plus.\n\nAnother alternative could be to build on AsciiDoc to get manpage\nand html output without relying too heavily on docbook\ntoolchain, and considering the fact that we still seem to be one\nof the most important customers listed on its home page, we\nmight be able to get help from Stuart himself to improve the\nsituation (I am assuming that mingwgit folks do not have problem\nwith Python, but I may be mistaken).\n\nIn short, although I do appreciate Johannes's and Sam's attempt,\nI would really prefer to see us pick some externally maintained\nalternative, instead of inventing a homebrew system that we need\nto maintain ourselves.  It is rumored that git has much higher\ndeveloper count vs loc count ratio than many other open source\nprojects, doing the documentation format is not part of our\nproject, and I'd rather see them spend time working on git, not\nbuilding and maintaining AsciiDoc lookalike.\n"},{"id":"54699","messageId":"Pine.LNX.4.64.0710031239410.28395@racer.site","threadId":"10121","inReplyTo":"7vprzwhkgd.fsf@gitster.siamese.dyndns.org","subject":"Re: [msysGit] Re: WIP: asciidoc replacement","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-10-03T11:50:01Z","receivedAt":"2007-10-03T11:50:01Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 2 Oct 2007, Junio C Hamano wrote:\n\n> \n> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n> \n> > So here it is: a perl script that does a good job on many .txt files \n> > in Documentation/, although for some it deviates from \"make man\"'s \n> > output, and for others it is outright broken.  It is meant to be run \n> > in Documentation/.\n> >\n> > My intention is not to fix the script for all cases, but to make \n> > patches to Documentation/*.txt themselves, so that they are more \n> > consistent (and incidentally nicer to the script).\n> \n> How you spend your time is up to you, but I need to wonder...\n> \n>  - Is \"man\" format important for msysGit aka Windows\n>    environment?  I had an impression that their helpfile format\n>    were closer to \"html\" output.\n\nI wanted something that can output both \"man\" and \"html\" output (and if \nsome suck^Wlos^Wtexi-fan wants to provide it, also a \"texi\" or even \"info\" \nbackend).\n\nIMHO \"man\" needs a stricter framework in place, so I went with that.\n\n>  - Does it make sense in the longer term for us to maintain\n>    in-house documentation tools?  Can we afford it?\n\nIn the long run, I expect only few bugs (and I will try hard to squash \nthem when they crop up, _and_ make this beast more maintainable whenever \nsomebody has an idea how to do that).\n\nHowever, it should definitely help keeping the docs clean, as now nobody \nhas an excuse to test doc changes a la \"I do not have asciidoc, so I do \nnot know if it works, so please test\".\n\n> It appears that we heard about breakages for every minor docbook \n> updates, and it is really appealing if we do not have to rely on xsl \n> toolchain for manpage generation.\n\nExactly.\n\n> But if patching the text means making it compatible with the in-house \n> script _and_ incompatible with AsciiDoc, hmmm...\n\nNo, I do not want it _incompatible_.  I want it _stricter_.  For example, \nyou can do this in asciidoc:\n\n\n    This is some paragraph that is indented,\n    but the funny thing is:\n\nThis paragraph:\n---------------\n\n\tis indented all the same!\n\n\nSo one thing I absolutely detest here is that you are free to use one, \ntwo, three or more spaces, or tabs, and asciidoc does the DWIMery of \nhandling them the same.  But _not_ if there was any indentation before \nthat with _less_ spaces and/or tabs!\n\nTherefore I'd like to enforce strict rules here: Tab it is.  One tab per \nindentation level.  No spaces, no ambiguities.\n\nCiao,\nDscho\n"},{"id":"54700","messageId":"854ph8v22l.fsf@lola.goethe.zz","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710031239410.28395@racer.site","subject":"Re: [msysGit] Re: WIP: asciidoc replacement","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-10-03T12:02:10Z","receivedAt":"2007-10-03T12:02:10Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> On Tue, 2 Oct 2007, Junio C Hamano wrote:\n>\n>> \n>> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n>> \n>> > So here it is: a perl script that does a good job on many .txt files \n>> > in Documentation/, although for some it deviates from \"make man\"'s \n>> > output, and for others it is outright broken.  It is meant to be run \n>> > in Documentation/.\n>> >\n>> > My intention is not to fix the script for all cases, but to make \n>> > patches to Documentation/*.txt themselves, so that they are more \n>> > consistent (and incidentally nicer to the script).\n>> \n>> How you spend your time is up to you, but I need to wonder...\n>> \n>>  - Is \"man\" format important for msysGit aka Windows\n>>    environment?  I had an impression that their helpfile format\n>>    were closer to \"html\" output.\n>\n> I wanted something that can output both \"man\" and \"html\" output (and\n> if some suck^Wlos^Wtexi-fan wants to provide it, also a \"texi\" or\n> even \"info\" backend).\n\nAnd you have not even talked about print.  The thing is that high\nquality output is a lot of work (including design and design\ndecisions) for _every_ _single_ backend.  If the only target were\n\"man\" and text, then one would be better off writing as groff source\nand be done.\n\nWe really can't afford another time sink.  That nobody can actually\nsolve structural problems (\"how do we include the man pages as an\nappendix in the user manual?\") also implies a waste of time, but at\nsome point of time people just throw up their hands and give up in\ndisgust.\n\nYou propose a larger time sink where people won't be forced to give\nup.  But we really don't want to waste time reinventing the wheel.  It\nwould be better spent communicating with the wheelbuilders.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"54708","messageId":"20071003134741.GQ21675@fieldses.org","threadId":"10121","inReplyTo":"85k5q4v6jb.fsf@lola.goethe.zz","subject":"Re: WIP: asciidoc replacement","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-10-03T13:47:41Z","receivedAt":"2007-10-03T13:47:41Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Wed, Oct 03, 2007 at 12:25:44PM +0200, David Kastrup wrote:\n> Wincent Colaiuta <win@wincent.com> writes:\n> \n> > El 3/10/2007, a las 10:12, David Kastrup escribió:\n> >\n> >> What with output in print, HTML, info?\n> >\n> > Yes, that's still a problem...\n> >\n> >> Personally, I think it might make sense to just step away from the\n> >> AsciiDoc documentation to Docbook: plain text (without cutified\n> >> formatting control like in AsciiDoc) can be generated _from_ Docbook.\n> >\n> > Yes, but editing DocBook (XML) is relatively painful compared to\n> > editing plain text.\n> \n> The problem is that we are not editing plain text, but Docbook source\n> masquerading as plain text.\n\nI do a fair amount of editing of the asciidoc source, but 99% of it is\ndone by just blind imitation of what's already there.  I've never\nlearned docbook (I've barely learned asciidoc, to be honest), and with a\nfew (now forgotten) exceptions haven't tried to understand how the\ntoolchain works.\n\nMaybe my experience would be the same with Docbook--I have no idea,\nnever having worked with it--but if you're suggesting that knowledge of\nDocbook is a prerequisite for working with asciidoc, that certainly\nhasn't been my experience.\n\n> But it is not all _all_ easily writeable the moment you try to do\n> something with _structural_ impact.  In fact, it is pretty much\n> impossible for anybody except wizards to do that.  And when the\n> wizards do it, they can't actually document what they have been doing\n> since that would mean cluttering the purported \"plain text\n> documentation\" with formatting comments.\n\nI'm not sure what you're talking about here.  Example?\n\n--b.\n"},{"id":"54709","messageId":"20071003135513.GR21675@fieldses.org","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710030506360.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-10-03T13:55:13Z","receivedAt":"2007-10-03T13:55:13Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Wed, Oct 03, 2007 at 05:23:35AM +0100, Johannes Schindelin wrote:\n> On Wed, 3 Oct 2007, Sam Vilain wrote:\n> > Johannes Schindelin wrote:\n> > \n> > > I do not want to depend on more than necessary in msysGit, and \n> > > therefore I started to write an asciidoc replacement.\n> > \n> > It's pretty good, I certainly wouldn't have trouble reading or \n> > maintaining it, but I'll give you suggestions anyway.\n> \n> Thank you very much!  (On both accounts...)\n> \n> > nice work, replacing a massive XML/XSL/etc stack with a small Perl \n> > script ;-)\n> \n> Uhm... It is less capable, though...\n\nBy the way, without having looked at your script to see it does, a\ncouple things I know of that the user manual relies on that other docs\nmay not as much are automatic table of contents generation, and cross\nreferences.\n\nI'd be similarly inclined to work on improving asciidoc rather than\ninventing something new, but I guess it's at least interesting to see\nhow far your approach gets us.\n\n--b.\n"},{"id":"54710","messageId":"85bqbgthyv.fsf@lola.goethe.zz","threadId":"10121","inReplyTo":"20071003134741.GQ21675@fieldses.org","subject":"Re: WIP: asciidoc replacement","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-10-03T14:01:44Z","receivedAt":"2007-10-03T14:01:44Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"\"J. Bruce Fields\" <bfields@fieldses.org> writes:\n\n> On Wed, Oct 03, 2007 at 12:25:44PM +0200, David Kastrup wrote:\n>\n>> The problem is that we are not editing plain text, but Docbook\n>> source masquerading as plain text.\n>\n> I do a fair amount of editing of the asciidoc source, but 99% of it\n> is done by just blind imitation of what's already there.\n\nBut not everything is already there, and when something surprising\nhappens, there is little chance to see how it came about.\n\n> Maybe my experience would be the same with Docbook--I have no idea,\n> never having worked with it--but if you're suggesting that knowledge\n> of Docbook is a prerequisite for working with asciidoc, that\n> certainly hasn't been my experience.\n\n\"making use of\" and \"working with\" are two different things.\n\n>> But it is not all _all_ easily writeable the moment you try to do\n>> something with _structural_ impact.  In fact, it is pretty much\n>> impossible for anybody except wizards to do that.  And when the\n>> wizards do it, they can't actually document what they have been\n>> doing since that would mean cluttering the purported \"plain text\n>> documentation\" with formatting comments.\n>\n> I'm not sure what you're talking about here.  Example?\n\nTry including the manual pages as a (properly linked when man pages\nare referenced) appendix in the user manual, so that the printed form\n(or PDF) of the user manual is a single coherent document with all\ninformation inside.  That's what I tried for about a week, digging\ninto the various available (and unavailable) documentation and then\npostponing the project indefinitely because it both exceeded my\ncurrent capability as well as demonstrating that there was no\nreasonably outlined path for acquiring the necessary skills.\n\nIn Texinfo, this takes few commands, all of which are well-documented\nand in a reasonable place in the Texinfo manual (which is all you need\nto consult in order to write Texinfo documents).\n\nBut with git's AsciiDoc information, not only is the required\ninformation scattered through half a dozen of different manuals all\ndescribing completely different systems, but the necessary other\ndocumentation is, at best, only mentioned in passing in every single\nrelevant document.  So while you may know where you want to start and\nend your journey, there is nothing which would tell you how to get\nfrom start to end.  You have to randomly pick your road until you may\nor may not find something closer to the end.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"54731","messageId":"20071003174659.GA13691@uranus.ravnborg.org","threadId":"10121","inReplyTo":"7vd4vwfou9.fsf@gitster.siamese.dyndns.org","subject":"Re: WIP: asciidoc replacement","fromName":"Sam Ravnborg","fromEmail":"sam@ravnborg.org","sentAt":"2007-10-03T17:46:59Z","receivedAt":"2007-10-03T17:46:59Z","isPatch":false,"sender":{"key":"sam@ravnborg.org","avatar":"https://gravatar.com/avatar/168a912606ed0742d840bb365e3cc21db390c36531a58341dc7a069cc1f15f62?d=mp&s=160"},"body":"Hi Junio.\n> \n> In short, although I do appreciate Johannes's and Sam's attempt,\n> I would really prefer to see us pick some externally maintained\n> alternative, instead of inventing a homebrew system that we need\n> to maintain ourselves.  It is rumored that git has much higher\n> developer count vs loc count ratio than many other open source\n> projects, doing the documentation format is not part of our\n> project, and I'd rather see them spend time working on git, not\n> building and maintaining AsciiDoc lookalike.\n\nFor the kernel I would like to see a tool that does:\n\no Based on nicely formatted ascii/utf-8 be able to:\n - Generate good looking and easy to read HTML\n - Possible generate other output formats too\n\nAnd if the kernel folks do not like it then at least the possibility\nto run this on kbuild documentation locally so I can generate nice\nhtml docs for that part.\n\nFor a kernel integrated tool the dependencies shall be minimal which\nis where asciidoc fails today. If asciidoc people could address this\nissue for the simpler output format then the tool IMO would\nhave a much stronger position.\n\n\tSam\n"},{"id":"54735","messageId":"Pine.LNX.4.64.0710031957170.28395@racer.site","threadId":"10121","inReplyTo":"20071003174659.GA13691@uranus.ravnborg.org","subject":"Re: WIP: asciidoc replacement","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-10-03T18:57:48Z","receivedAt":"2007-10-03T18:57:48Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 3 Oct 2007, Sam Ravnborg wrote:\n\n> For a kernel integrated tool the dependencies shall be minimal which is \n> where asciidoc fails today.\n\nIs perl not too much already?\n\nCiao,\nDscho\n"},{"id":"54739","messageId":"20071003192111.GA14277@uranus.ravnborg.org","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710031957170.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"Sam Ravnborg","fromEmail":"sam@ravnborg.org","sentAt":"2007-10-03T19:21:11Z","receivedAt":"2007-10-03T19:21:11Z","isPatch":false,"sender":{"key":"sam@ravnborg.org","avatar":"https://gravatar.com/avatar/168a912606ed0742d840bb365e3cc21db390c36531a58341dc7a069cc1f15f62?d=mp&s=160"},"body":"On Wed, Oct 03, 2007 at 07:57:48PM +0100, Johannes Schindelin wrote:\n> Hi,\n> \n> On Wed, 3 Oct 2007, Sam Ravnborg wrote:\n> \n> > For a kernel integrated tool the dependencies shall be minimal which is \n> > where asciidoc fails today.\n> \n> Is perl not too much already?\n\nNo - perl has not proved to be a problem.\nBut like git we have had a smaller share of docbook\nincompatibilities.\n\nWe even require perl for a regular kernel build\nfor some arch's these days.\n\n\tSam\n"},{"id":"54788","messageId":"47046875.1050605@vilain.net","threadId":"10121","inReplyTo":"Pine.LNX.4.64.0710030506360.28395@racer.site","subject":"Re: WIP: asciidoc replacement","fromName":"Sam Vilain","fromEmail":"sam@vilain.net","sentAt":"2007-10-04T04:13:41Z","receivedAt":"2007-10-04T04:13:41Z","isPatch":false,"sender":{"key":"sam@vilain.net","avatar":"https://gravatar.com/avatar/8fc840ca854dbf6f7065b4335e3b934951c1dca3b11db688e95e471901f8f4a8?d=mp&s=160"},"body":"Johannes,\n\nGiven other people have answered some points, I'll answer the rest.\n\nJohannes Schindelin wrote:\n>>> -- snip --\n>>> #!/usr/bin/perl\n>> Add -w for warnings, also use strict;\n> \n> <dumb>What does \"use strict;\" imply?</dumb>\n\nThree things;\n\n1. variables must be declared with 'my', 'our' or 'use var' before they\nare used, to catch typos\n\n2. when subroutine calls are found, they are checked to exist otherwise\nthey throw a compile-time error\n\n3. force all dereferences to follow real references and not allow symbol\ntable access (don't worry about that ;-))\n\n\n>>> sub handle_text {\n>> this function acts on globals; make them explicit arguments to the \n>> function.\n> \n> Actually, it resets the global $par.  Should I rather make it a class?\n\nWell, just channelling Dijkstra really.  Functions should take all their\ninput as formal arguments rather than globals.\n\nie\n\n  sub handle_text {\n      my $par = shift;\n  }\n\nIf it really should be a global, it is perhaps best declared up front\nwith \"our\" or \"use vars\".  \"use strict\" will force you to do one of these.\n\n>> also consider making this a \"tabular ternary\" with the actions in \n>> separate functions.\n>>\n>> ie\n>>\n>> $result = ( $par =~ /^\\. /s      ? $conv->do_enum($par)    :\n>>             $par =~ /^\\[verse\\]/ ? $conv->do_verse($par)  :\n>>             ... )\n> \n> I do not like that way... is it Perl standard to code like that?\n\nIt's in Perl Best Practices, but these are always suggestions and not\nhard and fast rules.  It just means that you have a big table of regex\n-> function that you can quickly check rather than looking at a lot of\nspaced out 'elsif's\n\n>>> \t\ts/gitlink:([^\\[ ]*)\\[(\\d+)\\]/sprintf \"%s\",\n>>> \t\t\t$conv->get_link($1, $2)/ge;\n>>> \t\t# handle link:\n>>> \t\ts/link:([^\\[ ]*)\\[(.+)\\]/sprintf \"%s\",\n>>> \t\t\t$conv->get_link($1, $2, 'external')/ge;\n>> These REs suffer from LTS (Leaning Toothpick Syndrome).  Consider using \n>> s{foo}{bar} and adding the 'x' modifier to space out groups.\n> \n> I guess you mean the forward slash.  Alas, that's what I'm used to, and \n> I'd rather not change it unless forced to... lest I stop understanding my \n> own code!\n> \n> (Besides, I did not find _any_ example showing why \"x\" should be useful.)\n\nBefore:\n\ns/link:([^\\[ ]*)\\[(.+)\\]/sprintf \"%s\",\n \t\t\t$conv->get_link($1, $2, 'external')/ge;\n\nAfter:\n\ns{ link: ([^\\[\\040]*) \\[(.+)\\] }\n { sprintf \"%s\", $conv->get_link($1, $2, 'external') }gex;\n\n>>> \tif ($self->{preamble_shown} == undef) {\n>>> \t\tprint '.\\\" disable hyphenation' . \"\\n\"\n>>> \t\t\t. '.nh' . \"\\n\"\n>>> \t\t\t. '.\\\" disable justification (adjust text to left'\n>>> \t\t\t\t. ' margin only)' . \"\\n\"\n>>> \t\t\t. '.ad l' . \"\\n\";\n>> Using commas rather than \".\" will safe you a concat when printing to\n>> filehandles, but that's a very small nit to pick :)\n> \n> Does that also work with older perl?  IIRC there was some strange problem \n> with my perl when lots of code in git.git was changed to using commata.\n\nThat should go back all the way to perl 4, if not earlier.  If you're\nassigning to a scalar, then you need to use concat.  But very minor.\n\n>> Hmm, that regex would not match for <<foo > bar>>, if you care you'd \n>> need to write something like <<((?:[^>]+|>[^>])*)>>\n> \n> I'd rather leave it as is -- this script is not meant to grok all kind of \n> sh*t.  It is meant to make translating the docs as fast and uncumbersome \n> as possible.  Which will involve making the documentation more consistent \n> (in and of itself something I rather like).\n> \n> So unless there comes a compelling reason, I'd rather leave it.\n\nSure, KISS.\n\n> Another thing: if I want to add some documentation, what would be the \n> common way to do it?  =pod...=cut?\n\nThat's right.  If you're an emacs user, in cperl-mode with abbrevs on\nyou type '=head1' and you'll get:\n\n=head1 NAME\n\nscriptname\n\n=head1 SYNOPSIS\n\n=head1 DESCRIPTION\n\n=cut\n\nSee perlpod(3) for more!\n\nSam.\n"},{"id":"54792","messageId":"46a038f90710032355t77c38d30p781743a6f248fab5@mail.gmail.com","threadId":"10121","inReplyTo":"7vd4vwfou9.fsf@gitster.siamese.dyndns.org","subject":"Re: WIP: asciidoc replacement","fromName":"Martin Langhoff","fromEmail":"martin.langhoff@gmail.com","sentAt":"2007-10-04T06:55:46Z","receivedAt":"2007-10-04T06:55:46Z","isPatch":false,"sender":{"key":"martin.langhoff@gmail.com","avatar":"https://gravatar.com/avatar/1e3f311b6c4c15836501901ca58f8c0b0667246488084ba524d8bc9867e22fd9?d=mp&s=160"},"body":"Junio,\n\ngreat summary!\n\nOn 10/3/07, Junio C Hamano <gitster@pobox.com> wrote:\n> One thing Linus had to say about the issue from early on, and I\n> still agree with, is the last paragraph in:\n>\n>     http://article.gmane.org/gmane.comp.version-control.git/2298\n\nI'm in complete agreement here...\n\n...\n> I've seen markdown used elsewhere, and I regularly read pod.\n...\n> How good are HTML and manpage output support from these (or\n> other candidates) formats these days?  Output to help page\n> format Windows folks use (I am assuming Mac people are happy as\n> long as man is available) would be a definite plus.\n\nAnd something that leads to PDF (perhaps via latex).\n\nThe problem I see here -- and that I've bumped into several times in\nother projects -- is that readable & easy to edit text formats for the\nsource are key, and those can do most of what we need for\nman/info/html outputs. But documentation formats that produce high\nquality print output usually need  arcane formats _and_ a\nhigh-maintenance toolchain.\n\nWith AsciiDoc we've managed to avoid the arcane format, but we are\nstill laden with a horrid toolchain. In that light, I actually like\nwhat Johannes is doing, even though it's a timesink.\n\nDo the other text based alternatives these days have a workable high\nquality PDF/latex output format without pulling in brittle\ndependencies like XSLT?\n\ncheers\n\n\nmartin\n"},{"id":"54812","messageId":"Pine.LNX.4.64.0710041340540.4174@racer.site","threadId":"10121","inReplyTo":"47046875.1050605@vilain.net","subject":"Re: WIP: asciidoc replacement","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2007-10-04T12:41:13Z","receivedAt":"2007-10-04T12:41:13Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 4 Oct 2007, Sam Vilain wrote:\n\n> Given other people have answered some points, I'll answer the rest.\n\nThanks for your patient explanations!\n\nCiao,\nDscho\n"},{"id":"54871","messageId":"85tzp6oavq.fsf@lola.goethe.zz","threadId":"10121","inReplyTo":"46a038f90710032355t77c38d30p781743a6f248fab5@mail.gmail.com","subject":"Re: WIP: asciidoc replacement","fromName":"David Kastrup","fromEmail":"dak@gnu.org","sentAt":"2007-10-04T20:58:17Z","receivedAt":"2007-10-04T20:58:17Z","isPatch":false,"sender":{"key":"dak@gnu.org","avatar":"https://avatars.githubusercontent.com/u/52141349?v=4"},"body":"\"Martin Langhoff\" <martin.langhoff@gmail.com> writes:\n\n> With AsciiDoc we've managed to avoid the arcane format, but we are\n> still laden with a horrid toolchain.\n\nLet's put this somewhat into perspective: the toolchain is horrid with\nregard to the complexity and documentation (well, AsciiDoc\ndocumentation itself is quite thorough and reasonably organized, but\nit does not buy you much without learning Docbook, and learning\nDocbook is such a chore that people would rather use AsciiDoc in order\nto avoid it), not horrid regarding the usability or flexibility of the\nresults.\n\nIf we had a few people specializing in Docbook/AsciiDoc/XSLT available\nconstantly on the team, we could probably get along fine.\n\n> In that light, I actually like what Johannes is doing, even though\n> it's a timesink.\n\nThe problem is not just that it is a timesink now, but that it will\nremain a timesink.  There is a reason that we don't have so many\nformats around with multiple high-quality backends.\n\n> Do the other text based alternatives these days have a workable high\n> quality PDF/latex output format without pulling in brittle\n> dependencies like XSLT?\n\nTexinfo produces good info and plain text, tolerable PDF and HTML and\nnot-quite-usable Docbook.  The output for HTML from the current git\ndocumentation toolchain certainly looks better.  I don't see how to\ngenerate PDF right now, but there must be a way (xmlto complains about\nnot seeing passivetex though I have it installed in TeXlive).\n\nThe source is uglier than AsciiDoc, but then there is no cleverly\ndisguised information in it: every formatting detail is quite out in\nthe open.  The same is true for Docbook, but Docbook really eats the\ncake, platter and all concerning unreadability of the input.  On the\nother hand, there are more special-purpose editors that know how to\ndeal with Docbook/XML than there are for Texinfo.\n\nTexinfo gives a reasonable subset of Linus-thinkalikes the cooties,\nand that pretty much rules it out: we need a format that people are\nwilling to write in.\n\nThere are not really many options for versatile formats, I am afraid.\n\n-- \nDavid Kastrup, Kriemhildstr. 15, 44793 Bochum\n"},{"id":"54887","messageId":"46a038f90710041549v3357a0f8j53b1d2fc24b73210@mail.gmail.com","threadId":"10121","inReplyTo":"85tzp6oavq.fsf@lola.goethe.zz","subject":"Re: WIP: asciidoc replacement","fromName":"Martin Langhoff","fromEmail":"martin.langhoff@gmail.com","sentAt":"2007-10-04T22:49:56Z","receivedAt":"2007-10-04T22:49:56Z","isPatch":false,"sender":{"key":"martin.langhoff@gmail.com","avatar":"https://gravatar.com/avatar/1e3f311b6c4c15836501901ca58f8c0b0667246488084ba524d8bc9867e22fd9?d=mp&s=160"},"body":"On 10/5/07, David Kastrup <dak@gnu.org> wrote:\n> \"Martin Langhoff\" <martin.langhoff@gmail.com> writes:\n>\n> > With AsciiDoc we've managed to avoid the arcane format, but we are\n> > still laden with a horrid toolchain.\n>\n> Let's put this somewhat into perspective: the toolchain is horrid with\n> regard to the complexity and documentation\n\nExactly. I'm not complaining about asciidoc itself. But the toolchain\nis very fragile, and not crossplatform. Git compiles and works on many\nunixen, win32, and some embedded posixy OSs if IIRC.\n\nOTOH asciidoc can be pretty hard to get going even on modern\nlinuxen.The asciidoc toolchain doesn't even work on Debian Sarge,\nwhich isn't *that* old, while I'm pretty sure git itself can be built\nand used on older linuxen. That's where a good old regex-insanity\nPerl-based parser beats anything else: no dependencies, works\neverywhere.\n\nIn that sense, this is close to being a rehash of the \"let's use\nautoconf\" argument...\n\ncheers\n\n\n\nmartin\n"}]}