The texinfo format provides 3 commands @ref, @xref and @pxref to make cross
references to existing @nodes in the document; it also provides a command
@anchor to place arbitrary targets for cross-reference.
Because these will be handy for the Installation Manual that already does
some references, this patch implements the 4 commands:
- change the '@node' command, that did nothing, to now track potential
reference points;
- add the '@anchor' command to register a new target for x-ref;
- implement the 3 '@*ref' commands with similar behaviour as the texinfo
format states, with support for all arguments, generating a temporary
"@x##@" pattern for the line target;
- generate a new file (*.xrf, a sed script) at the end with the
replacement for x-ref patterns with the correct line number, and perform
a few consistency checks;
- during the final search-and-replace used to insert the Table of Content,
include the x-ref replacement.
The current script has some limitations:
- because we cannot know in advance the target line number for the x-ref,
we insert it with a constant size of 5 characters to avoid breaking the
justification alignment when doing the replace;
- there is a strict order to respect between @node and @chapter/@section,
which is needed because we have to include a line offset to get it right
when using the order given in the texinfo manual.
Signed-off-by: Christophe CURIS
---
script/generate-txt-from-texi.sh | 129 +--
1 file changed, 125 insertions(+), 4 deletions(-)
diff --git a/script/generate-txt-from-texi.sh b/script/generate-txt-from-texi.sh
index e56d78a..5554e6e 100755
--- a/script/generate-txt-from-texi.sh
+++ b/script/generate-txt-from-texi.sh
@@ -60,6 +60,10 @@
# - There are 2 blank lines instead of 1 before chapter/section to make
# them stand out more
#
+# - when making cross-references, generate a decent-looking string with
+# the target line number, instead of the crypting "*Note:" label (inherited
+# from "info" format) that looks out of place
+#
# - the line length is set to 76 instead of 72
#
# - there are some difference in what characters are added when a style is
@@ -73,6 +77,13 @@
# - not all commands are implemented, some because they were not needed
# so far, probably a few because they would be too complex to implement
#
+#
+# There are a few limitations due to Texinfo being a cheesy format:
+#
+# - the @node should be followed immediately by its @chapter/@section
+# command, otherwise you may have mismatch on the line number if you make a
+# cross-reference to that @node
+#
###
#
# Please note that this script is writen in sh+awk on purpose: this script
@@ -157,6 +168,7 @@ done
# Create the temp file in the current directory
temp_file="`echo "$input_file" | sed -e 's,^.*/\([^/]*\)$,\1, ; s,\.[^.]*$,,'
`.tmp"
toc_file="`echo "$temp_file" | sed -e 's,\.[^.]*$,,' `.toc"
+xref_file="`echo "$temp_file" | sed -e 's,\.[^.]*$,,' `.xrf"
# Run awk for 1st pass, but if it fails stop now without deleting temp files
awk '
@@ -448,6 +460,36 @@ function new_section(level, title, is_numbered,
local_i, local_line) {
par_indent = 0;
}
+# Do not generate anything for Node command, but keep the line information so
+# the nodes can be cross-referenced
+function new_node(args,local_nb, local_arr, local_i) {
+ if (!cond_state) { return; }
+
+ # Dump the current paragraph now
+ generate_paragraph();
+
+ # The command takes many arguments, separate them because we care only for
the 1st
+ local_nb = split(args, local_arr, ",");
+ if ((local_nb < 1) || (local_nb > 4)) {
+report_error("bad number of argument " local_nb " for @node at line " NR);
+ }
+ gsub(/^[ \t]*/, "", local_arr[1]);
+ gsub(/[ \t]*$/, "", local_arr[1]);
+ if (local_arr[1] == "") {
+report_error("missing node name for @node at line " NR);
+ }
+
+ # Consistency check
+ if (node_address[local_arr[1]] != "") {
+report_error("node \"" local_arr[1] "\" is redefined at line " NR ",
previous definition at line " node_defline[local_arr[1]]);
+ }
+
+ # Add a +3 offset to compensate for the position of the real location that
will be the
+ # chapter/section that should be following
+ node_address[local_arr[1]] = line_number + 3;
+ node_defline[local_arr[1]] = NR;
+}
+
# List of Items
function start_item_list(mark, type, default_mark) {
par_mode_push(type);
@@ -521,6 +563,48 @@ function generate_url_reference(args, local_nb,
local_arr) {
}
}
+# Generate text for a Cross-Reference into the document
+function generate_cross_reference(args, cmd, local_nb, local_arr,
local_i) {
+ local_nb = split(args, local_arr, ",");
+ if ((local_nb < 1) || (local_nb > 5)) {
+report_error("bad number of argument " local_nb " for @" cmd " at line "
NR);
+ }
+
+ local_arr[1] = execute_commands(local_arr[1]);
+ for (local_
