Re: WIP: asciidoc replacement
- From
Johannes Schindelin <johannes.schindelin@gmx.de>
- Date
- Oct 3, 2007, 04:23 UTC
- Message-ID
- <Pine.LNX.4.64.0710030506360.28395@racer.site>
- In-Reply-To
- <4702F6BB.60908@vilain.net>
Hi,
On Wed, 3 Oct 2007, Sam Vilain wrote:
Show 7 quoted lines
> Johannes Schindelin wrote: > > > I do not want to depend on more than necessary in msysGit, and > > therefore I started to write an asciidoc replacement. > > It's pretty good, I certainly wouldn't have trouble reading or > maintaining it, but I'll give you suggestions anyway.
Thank you very much! (On both accounts...)
> nice work, replacing a massive XML/XSL/etc stack with a small Perl > script ;-)
Uhm... It is less capable, though...
> > -- snip -- > > #!/usr/bin/perl > > Add -w for warnings, also use strict;
<dumb>What does "use strict;" imply?</dumb>
> > sub handle_text {
>
> this function acts on globals; make them explicit arguments to the
> function.Actually, it resets the global $par. Should I rather make it a class?
Show 7 quoted lines
> > if ($par =~ /^\. /s) {
> > my @lines = split(/^\. /m, $par);
> > shift @lines;
> > $conv->enumeration(\@lines);
> > } elsif ($par =~ /^\* /s) {
>
> uncuddle your elsif's;I'm sorry... What do you mean?
Show 8 quoted lines
> also consider making this a "tabular ternary" with the actions in > separate functions. > > ie > > $result = ( $par =~ /^\. /s ? $conv->do_enum($par) : > $par =~ /^\[verse\]/ ? $conv->do_verse($par) : > ... )
I do not like that way... is it Perl standard to code like that?
Show 5 quoted lines
> However I have a suspicion that your script is doing line-based parsing > instead of recursive descent; I don't know whether that's the right > thing for asciidoc. It's actually fairly easy to convert a grammar to > code blocks using tricks from MJD's _Higher Order Perl_. Is it > necessary for the asciidoc grammar?
I wanted to keep it simple. So I'll try to stay away from any fancy grammar parsing, and stay with "read lines until you have something to process".
Show 9 quoted lines
> > # handle gitlink:
> > s/gitlink:([^\[ ]*)\[(\d+)\]/sprintf "%s",
> > $conv->get_link($1, $2)/ge;
> > # handle link:
> > s/link:([^\[ ]*)\[(.+)\]/sprintf "%s",
> > $conv->get_link($1, $2, 'external')/ge;
>
> These REs suffer from LTS (Leaning Toothpick Syndrome). Consider using
> s{foo}{bar} and adding the 'x' modifier to space out groups.I guess you mean the forward slash. Alas, that's what I'm used to, and I'd rather not change it unless forced to... lest I stop understanding my own code!
(Besides, I did not find _any_ example showing why "x" should be useful.)
Show 13 quoted lines
> > if ($self->{preamble_shown} == undef) {
> > $title = $text;
> > $title =~ s/\(\d+\)$//;
> > print '.\" Title: ' . $title
> > . '.\" Author: ' . "\n"
> > . '.\" Generator: ' . $self->{generator} . "\n"
> > . '.\" Date: ' . $self->{date} . "\n"
> > . '.\" Manual: ' . $self->{manual} . "\n"
> > . '.\" Source: ' . $self->{git_version} . "\n"
> > . '.\"' . "\n";
> > }
>
> I'd consider a HERE-doc, or multi-line qq{ } more readable than this.Can you give me an example of a HERE-doc? (What I tried to avoid is having ugly indentation-breaking tlobs.)
Show 6 quoted lines
> > $text =~ tr/a-z/A-Z/;
> > my $suffix = "\"$self->{date}\" \"$self->{git_version}\""
> > . " \"$self->{manual}\"";
>
> Use qq{} when making strings with lots of embedded double quotes and
> interpolation.I'll try to find something about qq{} in the docs.Show 12 quoted lines
> > $text =~ s/^(.*)\((\d+)\)$/.TH "\1" "\2" $suffix/;
> > print $text;
> >
> > if ($self->{preamble_shown} == undef) {
> > print '.\" disable hyphenation' . "\n"
> > . '.nh' . "\n"
> > . '.\" disable justification (adjust text to left'
> > . ' margin only)' . "\n"
> > . '.ad l' . "\n";
>
> Using commas rather than "." will safe you a concat when printing to
> filehandles, but that's a very small nit to pick :)Does that also work with older perl? IIRC there was some strange problem with my perl when lots of code in git.git was changed to using commata.
Show 5 quoted lines
> > # handle <<sections> > > $text =~ s/<<([^>]*)>>/the section called \\(lq\1\\(rq/g; > > Hmm, that regex would not match for <<foo > bar>>, if you care you'd > need to write something like <<((?:[^>]+|>[^>])*)>>
I'd rather leave it as is -- this script is not meant to grok all kind of sh*t. It is meant to make translating the docs as fast and uncumbersome as possible. Which will involve making the documentation more consistent (in and of itself something I rather like).
So unless there comes a compelling reason, I'd rather leave it.
Show 9 quoted lines
> > sub begin_item {
> > my ($self, $item, $text) = @_;
> >
> > $item = $self->common($item);
> > $text = $self->common($text);
> >
> > $text =~ s/([^\n]) *\n([^\n])/\1 \2/g;
>
> "." is the same as [^\n] (without the 's' modifier).But I need the (implicit) 's' modifier, otherwise the "\n" in the middle is not interpreted correctly. This regsub is meant to unwrap the paragraph and put it into a very long line (but leaving \n\n alone).
Show 10 quoted lines
> > sub finish {
> > my ($self) = @_;
> > my $links = $self->{links};
> >
> > if ($#$links >= 0) {
> > print '.SH "REFERENCES"' . "\n";
> > my $i = 1;
> > while ($#$links >= 0) {
>
> just use if (@$links) and while (@$links)Thanks. I hoped there would be something like this.
Another thing: if I want to add some documentation, what would be the common way to do it? =pod...=cut?
Thank you for all your tips!
Ciao, Dscho