[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
gEDA-user: command line options in the pcb manual
The command line option section of the pcb manual is totally out of sync
with the current binary. Almost none of the options mentioned there still
works as described. A few weeks a go, I did a first stab to derive the
entries in the manual from special comments in the source like it is already
done with actions. However, the extraction script could only deal with
single word headings and the nodes were rigidly sorted according to
alphabet.
Today, I expanded the syntax of the already existing special comments a
little. Optional quotation marks around the heading string allow for more
complex headings. Any leading digits are removed after sorting the keys,
but before creation of headings. This allows to manipulate order of headings
in the manual. The old syntax is still valid. Existing special comments for
actions are not affected.
A special comment with the expanded syntax looks like this:
/------------------------------------------
/* %start-doc options "4 Layer Names"
@ftable @code
@item --layer-name-5 <string>
Name of the 5th Layer. Default is @code{"signal1"}.
@end ftable
%end-doc
*/
LAYERNAME (5, "signal1"),
\-------------------------------------------
I put the command line section of the manual with comments extracted from
source to my webspace:
http://lilalaser.de/tmp/pcb_commandline_options.pdf
A patch for extract-docs produced by "git format-patch -1" is attached to
this mail. There are of course numerous further patches that add special
comments to the source.
Anything I should tweak, to get this set of patches applied?
---<)kaimartin(>---
--
Kai-Martin Knaak
Ãffentlicher PGP-SchlÃssel:
http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x6C0B9F53From 892fd952dbb2170bdcaf6897d9fe836830b368c0 Mon Sep 17 00:00:00 2001
From: Kai-Martin Knaak <kmk@xxxxxxxxxxxx>
Date: Mon, 12 Apr 2010 02:25:47 +0200
Subject: [PATCH] expand the syntax of documentating comments
This is part of the effort to derive the command line option entries in the
manual dynamically from the source. The expanded syntax allows for more control on
the actual headings rendered in the manual.
1) accept keys enclosed in quotation marks ("). This allows for multiple word
nodes in the documentation.
2) strip leading digits of the key after sort. This allows to control the order
of nodes from the source.
---
doc/extract-docs | 27 +++++++++++++++++++++++++--
1 files changed, 25 insertions(+), 2 deletions(-)
diff --git a/doc/extract-docs b/doc/extract-docs
index cf23c6c..a25de8e 100755
--- a/doc/extract-docs
+++ b/doc/extract-docs
@@ -3,7 +3,11 @@
#
# $Id$
#
-
+#################################################################
+# This script extracts special comments from the source. It assembles
+# them in texinfo files that are included in the manual.
+#################################################################
+#
# The general format of what this script looks for is thusly:
#
# %start-doc category sort-key
@@ -18,6 +22,10 @@
# file according to the category. Each unique sort-key causes a @node
# to be created, unless that sort-key's text already has a @node in
# it.
+# If the sort-key contains space characters, it should be enclosed by
+# quotation marks ("). Leading digits in the sort key optionally followed
+# by space are removed after sort but before creation of nodes. This
+# allows to manipulate the order of nodes in the manual.
#
# Note that we synthesize a special @syntax command, which should be
# used for all things syntax. We change those to whatever the current
@@ -145,6 +153,8 @@ for $cat (sort keys %text) {
}
next if $key =~ /^00/;
$k2 = $title{$cat}{$key};
+ # strip leading digits from the key string
+ $k2 =~ s/\A\d+\s*//g;
$k2 = sprintf($nodename, $k2);
if ($text{$cat}{$key} !~ /\@node/) {
$new .="* ${k2}::\n";
@@ -161,6 +171,8 @@ for $cat (sort keys %text) {
}
next if $key =~ /^00/;
$k2 = $title{$cat}{$key};
+ # strip leading digits from the key string
+ $k2 =~ s/\A\d+\s*//g;
$k2n = sprintf($nodename, $k2);
$new .= "\@c $cat $k2\n";
if ($text{$cat}{$key} !~ /\@node/) {
@@ -261,9 +273,20 @@ sub scan_file {
next;
}
- if (/%start-doc\s+(\S+)\s+(\S+)(\s+(.*))?/) {
+ if (/%start-doc\s+(\S+)\s+([^"^\s]+|".*?")(\s+(.*))?/) {
+ # pattern to look for:
+ # start-doc -> "%start-doc"
+ # \s+ -> one ore more whitespace
+ # (\S+) -> string with no whitespace, goes to $1
+ # \s+ -> one ore more whitespace
+ # ([^"^\s]+|".*?") -> a space-less string, or a string delimited by ", goes to $2
+ # (\s+(.*))? -> zero or more space separated strings
+
$cat = $1;
$key = $2;
+ # strip leading and trailing quotation marks from the key string
+ $key =~ s/\A"//g;
+ $key =~ s/"\Z//g;
$title = $4;
if ($title) {
$title{$cat}{"$key\0$hid"} = $title;
--
1.7.0
_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user