mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Robert Schwebel <r.schwebel@pengutronix.de>
To: barebox@lists.infradead.org
Subject: [PATCH 02/21] doc: add macros to unify command help with doxygen
Date: Mon,  1 Nov 2010 09:33:35 +0100	[thread overview]
Message-ID: <1288600434-6112-3-git-send-email-r.schwebel@pengutronix.de> (raw)
In-Reply-To: <1288600434-6112-1-git-send-email-r.schwebel@pengutronix.de>

Currently we have duplicated all the information that appears online in
'help <command>' and in the doxygen documentation. This patch adds some
infrastructure to specify help texts only once and re-use them for the
integrated help as well as for the manual.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
 Doxyfile                |    2 +-
 include/command.h       |    9 ++++
 scripts/doxy_filter.awk |  103 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 113 insertions(+), 1 deletions(-)
 create mode 100644 scripts/doxy_filter.awk

diff --git a/Doxyfile b/Doxyfile
index 912abc1..23f3e43 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -575,7 +575,7 @@ IMAGE_PATH             =
 # to standard output.  If FILTER_PATTERNS is specified, this tag will be
 # ignored.
 
-INPUT_FILTER           =
+INPUT_FILTER           = "awk -f scripts/doxy_filter.awk"
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis.  Doxygen will compare the file name with each pattern and apply the
diff --git a/include/command.h b/include/command.h
index 0be7a69..e221546 100644
--- a/include/command.h
+++ b/include/command.h
@@ -89,6 +89,15 @@ const struct command __barebox_cmd_##_name						\
 #define BAREBOX_CMD_END					\
 };
 
+#define BAREBOX_CMD_HELP_START(_name) \
+static const __maybe_unused char cmd_##_name##_help[] =
+
+#define BAREBOX_CMD_HELP_USAGE(_name) "Usage: " _name
+#define BAREBOX_CMD_HELP_SHORT(_text) _text
+#define BAREBOX_CMD_HELP_OPT(_opt, _desc) _opt "\t" _desc
+#define BAREBOX_CMD_HELP_TEXT(_text)
+#define BAREBOX_CMD_HELP_END ;
+
 #ifdef CONFIG_LONGHELP
 #define BAREBOX_CMD_HELP(text)	.help = text,
 #else
diff --git a/scripts/doxy_filter.awk b/scripts/doxy_filter.awk
new file mode 100644
index 0000000..5ec0406
--- /dev/null
+++ b/scripts/doxy_filter.awk
@@ -0,0 +1,103 @@
+#!/usr/bin/awk
+
+/BAREBOX_CMD_HELP_START[[:space:]]*\((.*)\)/ {
+
+	this_opt = 0;
+	my_usage = "";
+	my_short = "";
+	my_cmd = gensub("BAREBOX_CMD_HELP_START[[:space:]]*\\((.*)\\)", "\\1", "g");
+	this_text = 0;
+	delete(my_text);
+	delete(my_opts);
+	next;
+}
+
+/BAREBOX_CMD_HELP_USAGE[[:space:]]*\((.*)\)/ {
+
+	$0 = gensub("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "g");
+	$0 = gensub("BAREBOX_CMD_HELP_USAGE[[:space:]]*\\((.*)\\)", "\\1", "g");
+	$0 = gensub("\\\\n", "", "g");
+	my_usage = gensub("\"", "", "g");
+	next;
+
+}
+
+/BAREBOX_CMD_HELP_SHORT[[:space:]]*\((.*)\)/ {
+
+	$0 = gensub("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "g");
+	$0 = gensub("BAREBOX_CMD_HELP_SHORT[[:space:]]*\\((.*)\\)", "\\1", "g");
+	$0 = gensub("\\\\n", "", "g");
+	my_short = gensub("\"", "", "g");
+	next;
+
+}
+
+/BAREBOX_CMD_HELP_OPT[[:space:]]*\([[:space:]]*(.*)[[:space:]]*,[[:space:]]*(.*)[[:space:]]*\)/ {
+
+	$0 = gensub("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "g");
+	$0 = gensub("@", "\\\\@",    "g");	
+	$0 = gensub("BAREBOX_CMD_HELP_OPT[[:space:]]*\\([[:space:]]*\"*(.*)\"[[:space:]]*,[[:space:]]*\"(.*)\"[[:space:]]*\\)", \
+		"<tr><td><tt> \\1 </tt></td><td>\\&nbsp;\\&nbsp;\\&nbsp;</td><td> \\2 </td></tr>", "g");
+	$0 = gensub("\\\\n", "", "g");
+	my_opts[this_opt] = gensub("\"", "", "g");
+	this_opt ++;
+	next;
+}
+
+/BAREBOX_CMD_HELP_TEXT[[:space:]]*\((.*)\)/ {
+
+	$0 = gensub("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "g");
+	$0 = gensub("BAREBOX_CMD_HELP_TEXT[[:space:]]*\\((.*)\\)", "\\1", "g");
+	$0 = gensub("\\\\n", "<br>", "g");
+	my_text[this_text] = gensub("\"", "", "g");
+	this_text ++;
+	next;
+}
+
+/BAREBOX_CMD_HELP_END/ {
+
+	printf "/**\n";
+	printf " * @page " my_cmd "_command " my_cmd "\n";
+	printf " *\n";
+	printf " * \\par Usage:\n";
+	printf " * " my_usage "\n";
+	printf " *\n";
+
+	if (this_opt != 0) {
+		printf " * \\par Options:\n";
+		printf " *\n";
+		printf " * <table border=\"0\" cellpadding=\"0\">\n";
+		n = asorti(my_opts, my_opts_sorted);
+		for (i=1; i<=n; i++) {
+			printf " * " my_opts[my_opts_sorted[i]] "\n";
+		}
+		printf " * </table>\n";
+		printf " *\n";
+	}
+
+	printf " * " my_short "\n";
+	printf " *\n";
+
+	n = asorti(my_text, my_text_sorted);
+	if (n > 0) {
+		for (i=1; i<=n; i++) {
+			printf " * " my_text[my_text_sorted[i]] "\n";
+		}
+		printf " *\n";
+	}
+
+	printf " */\n";
+
+	next;
+}
+
+/^.*$/ {
+
+	print $0;
+
+}
+
-- 
1.7.2.3


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

  parent reply	other threads:[~2010-11-01  8:34 UTC|newest]

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2010-11-01  8:33 Unified Documentation Robert Schwebel
2010-11-01  8:33 ` [PATCH 01/21] doc: fix typo Robert Schwebel
2010-11-01  8:33 ` Robert Schwebel [this message]
2010-11-01  8:33 ` [PATCH 03/21] doc: add documentation for 'bmp' Robert Schwebel
2010-11-01  8:33 ` [PATCH 04/21] doc: add documentation for 'clear' Robert Schwebel
2010-11-01  8:33 ` [PATCH 05/21] doc: add documentation for 'crc32' Robert Schwebel
2010-11-01  8:33 ` [PATCH 06/21] doc: add documentation for 'dfu' Robert Schwebel
2010-11-01  8:51   ` Baruch Siach
2010-11-01 10:03     ` Robert Schwebel
2010-11-01  8:33 ` [PATCH 07/21] doc: unify documentation for 'ls' Robert Schwebel
2010-11-01  8:33 ` [PATCH 08/21] doc: unify documentation for 'cat' Robert Schwebel
2010-11-01  8:33 ` [PATCH 09/21] doc: unify documentation for 'cd' Robert Schwebel
2010-11-01  8:33 ` [PATCH 10/21] doc: add documentation for 'echo' Robert Schwebel
2010-11-01  8:33 ` [PATCH 11/21] doc: unify documentation for 'edit' Robert Schwebel
2010-11-01  8:33 ` [PATCH 12/21] doc: add documentation for 'bootm' Robert Schwebel
2010-11-01  8:33 ` [PATCH 13/21] doc: unify documentation for 'addpart' Robert Schwebel
2010-11-01  8:33 ` [PATCH 14/21] doc: unify documentation for 'cp' Robert Schwebel
2010-11-01  8:33 ` [PATCH 15/21] doc: unify documentation for 'delpart' Robert Schwebel
2010-11-01  8:33 ` [PATCH 16/21] doc: rework user manual Robert Schwebel
2010-11-01  8:33 ` [PATCH 17/21] doc: unify documentation for 'devinfo' Robert Schwebel
2010-11-01  8:33 ` [PATCH 18/21] doc: unify documentation for 'erase' Robert Schwebel
2010-11-01  8:33 ` [PATCH 19/21] doc: rework and unify documentation for gpio commands Robert Schwebel
2010-11-01  8:33 ` [PATCH 20/21] doc: unify documentation for 'export' Robert Schwebel
2010-11-01  8:33 ` [PATCH 21/21] doc: unify documentation for 'tftp' Robert Schwebel

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

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1288600434-6112-3-git-send-email-r.schwebel@pengutronix.de \
    --to=r.schwebel@pengutronix.de \
    --cc=barebox@lists.infradead.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.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox