From: david@tethera.net
To: notmuch@notmuchmail.org
Cc: David Bremner <bremner@unb.ca>
Subject: [PATCH 2/4] Perl script to generate online help.
Date: Wed, 3 Nov 2010 14:18:54 -0300 [thread overview]
Message-ID: <1288804736-5173-3-git-send-email-david@tethera.net> (raw)
In-Reply-To: <874oc4r4bu.fsf@yoom.home.cworth.org>
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3410 bytes --]
From: David Bremner <bremner@unb.ca>
This is a bit more complicated than expected, mainly because it needs
to split a chunk of the docs into 3 pieces corresponding to the
strings currently filled into a struct command_t.
To disable the ANSI escape codes, replace Pod::Text:Color with
Pod::Text. It would not be that much more work to generate colorized
and uncolorized help strings, and choose at runtime.
---
pod2help_h.pl | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 108 insertions(+), 0 deletions(-)
create mode 100644 pod2help_h.pl
diff --git a/pod2help_h.pl b/pod2help_h.pl
new file mode 100644
index 0000000..99cfb96
--- /dev/null
+++ b/pod2help_h.pl
@@ -0,0 +1,108 @@
+#!/usr/bin/perl
+
+# Copyright © David Bremner, 2010
+# This file is distributed under the same terms as perl, Artistic or GPL 1+.
+#
+# Authors: David Bremner <david@tethera.net>
+
+use Pod::Select;
+use Pod::Text::Color;
+use strict;
+
+# Create customized version of Pod::Select, that uses Pod::Text to
+# format pieces of the file.
+
+package OurParser;
+our @ISA = qw(Pod::Select);
+
+sub new{
+ my $class = shift;
+ my $self = { body => "" , name => undef};
+ bless $self, $class;
+ $self->initialize();
+ return $self;
+}
+
+# process verbatim blocks, err, verbatimly. Note that $self->{body} is
+# processed a second time by Pod::Text
+
+sub verbatim {
+ my ($self,$text,$line_num,$pod_para)=@_;
+
+ $self->{body} .= $text;
+}
+
+# process a normal text or command block. Either do some command
+# starting with =for, append to text to be process, or process the
+# current section. Note that this has the weakness/bug that nested
+# sections are not supported as chunks of text for help.
+sub textblock{
+ my ($self,$text,$line_num,$pod_para) = @_;
+
+ my $cmd = $pod_para -> cmd_name;
+
+ if ($cmd =~ /^head/){
+
+ $self->output() if defined($self->{name});
+
+ # grab name heuristically as the first word.
+ $text =~ m/\s*\w+\s+([\w-]+)/;
+ $self->{name} = $1;
+ $self->{name} =~s/-/_/;
+
+ } elsif ($cmd =~ /^for/){
+
+ $text =~ s/^\s+//;
+ $text =~ s/\s+$//;
+
+ # work around a pod bug/misfeature that requires a blank line between
+ # =for paragraphs.
+
+ my @lines=split("\n",$text);
+ foreach my $line (@lines){
+
+ $line =~ s/^=for\s+help\s+//;
+
+ # override name if specified.
+ $self->{name} = $1 if ($line =~ m/^name\s+(.*)$/);
+
+ # other "subcommands" could be supported here.
+ if ($line =~ s/^(args|desc)\s+//) {
+ my $quote="\"";
+ my $subcmd=$1;
+
+ # special case NULL; we don't want "NULL"
+ $quote = "" if ($line =~ /^NULL/);
+
+ print ("#define HELP_$self->{name}_$subcmd $quote$line$quote\n");
+ }
+ }
+ } else {
+ $self->{body} .= $text;
+ }
+}
+
+sub output {
+ my $self = shift;
+ my $formatter = new Pod::Text::Color(margin=>4);
+ my $output;
+ $formatter -> output_string (\$output);
+ $formatter -> parse_string_document ("=pod\n\n".$self->{body});
+
+ # post-process to turn into a C string.
+ $output =~ s/"/\\"/g;
+ $output =~ s/\n/\\n"\\\n"/g;
+ $output =~ s/\e/\\e/g;
+
+ print "#define HELP_$self->{name}_text \\\n\"$output\"\n";
+ $self->{body} = "";
+
+}
+
+package main;
+
+my $parser = new OurParser();
+
+$parser->select("Commands/..*","Search Syntax");
+$parser->parse_from_filehandle(\*STDIN);
+$parser->output();
--
1.7.1
next prev parent reply other threads:[~2010-11-03 17:19 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2009-12-31 17:39 [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand david
2010-04-24 14:04 ` David Bremner
2010-04-26 10:56 ` David Edmondson
2010-04-26 23:33 ` Carl Worth
2010-04-26 23:49 ` David Bremner
2010-06-13 15:01 ` david
2010-10-29 23:01 ` Carl Worth
2010-11-03 17:18 ` generate help from pod david
2010-11-03 17:18 ` [PATCH 1/4] notmuch.pod: pod version of documentation, converted by rman, massaged by hand david
2010-11-03 17:18 ` david [this message]
2010-11-03 17:18 ` [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file david
2010-11-03 17:29 ` David Bremner
2010-11-03 17:18 ` [PATCH 4/4] notmuch.c: use help strings generated from notmuch.pod david
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1288804736-5173-3-git-send-email-david@tethera.net \
--to=david@tethera.net \
--cc=bremner@unb.ca \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).