[PATCH] Improved ALIASES definitions

Markus Geimer <[email protected]> Wed, 02 Oct 2013 12:50:53 +0200
Newsgroups gmane.text.doxygen.devel
Message-ID <[email protected]> 
Hi,

please find two patches attached regarding the definition of ALIASES.
The first one simply fixes a typo in an error message. The second
patch implements escaping of commands using the \-syntax in the value
part of ALIASES.

Rationale:
So far, there was no way to disambiguate a forced newline (via '\n')
from a command using the \-syntax starting with 'n'. While special
handling was implemented for some internal commands, self-defined
commands or LaTeX commands inside a \latexonly environment were not
recognized. For example, it was impossible to properly define a
command inserting a newline followed by a page break only for the
LaTeX output, as the '\newpage' in

	newpage="\latexonly\n\newpage\endlatexonly"

was recognized as '\n' followed by the text 'ewpage'.

Proposed solution:
The attached patch implements C-style escaping for the value part of
ALIASES. That is, '\n' inserts a newline, '\"' a quote character,
'\\' a backslash, and '\<num>' expands the corresponding argment.
The aforementioned command can therefore now be defined as either

	newpage="\\latexonly\n\\newpage\\endlatexonly"
or
	newpage"@latexonly\n\\newpage@endlatexonly"

While this solution is admittedly not backwards-compatible, it is
IMO preferable over only escaping '\n's as it provides a consistent
escaping scheme that is easy to remember.

Cheers,
Markus

------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from 
the latest Intel processors and coprocessors. See abstracts and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk

_______________________________________________
Doxygen-develop mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/doxygen-develop
0001-Fix-error-message-regarding-alias-format.patch (text/x-patch, 944 B) 
>From ee00b2ebee16cf638b9a76488441a14777994216 Mon Sep 17 00:00:00 2001
From: Markus Geimer <[email protected]>
Date: Mon, 30 Sep 2013 11:25:46 +0200
Subject: [PATCH 1/2] Fix error message regarding alias format

Use curly braces instead of normal braces for argument number in error
message.
---
 src/config.l |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/src/config.l b/src/config.l
index 19f0267..f35f6cb 100644
--- a/src/config.l
+++ b/src/config.l
@@ -1208,7 +1208,7 @@ void Config::check()
     alias=alias.stripWhiteSpace();
     if (alias.find(re1)!=0 && alias.find(re2)!=0)
     {
-      config_err("Error: Illegal alias format `%s'. Use \"name=value\" or \"name(n)=value\", where n is the number of arguments\n",
+      config_err("Error: Illegal alias format `%s'. Use \"name=value\" or \"name{n}=value\", where n is the number of arguments\n",
 	  alias.data());
     }
     s=aliasList.next();
-- 
1.7.2.5
0002-Implement-escaping-of-commands-in-ALIASES-definition.patch (text/x-patch, 8 KB) 
>From b5ea511048e8bfb3c0cfd3eabb32b2780559850d Mon Sep 17 00:00:00 2001
From: Markus Geimer <[email protected]>
Date: Wed, 2 Oct 2013 12:03:31 +0200
Subject: [PATCH 2/2] Implement escaping of commands in ALIASES definitions

To disambiguate forced newlines (\n's) from commands using the \-syntax
starting with an 'n' character in the value part of ALIASES definitions,
all commands now have to be escaped with a backslash.
---
 addon/doxywizard/configdoc.cpp |    3 ++-
 doc/commands.doc               |   10 +++++-----
 doc/config.doc                 |    2 ++
 doc/custcmd.doc                |   14 ++++++++------
 src/config.xml                 |    2 ++
 src/configoptions.cpp          |    3 ++-
 src/doxygen.cpp                |   26 ++++++++++++++++----------
 testing/009_bug.cpp            |    2 +-
 8 files changed, 38 insertions(+), 24 deletions(-)

diff --git a/addon/doxywizard/configdoc.cpp b/addon/doxywizard/configdoc.cpp
index 5bcccb6..72ecd75 100644
--- a/addon/doxywizard/configdoc.cpp
+++ b/addon/doxywizard/configdoc.cpp
@@ -222,7 +222,8 @@ void addConfigDocs(DocIntf *doc)
               "will allow you to put the command \\sideeffect (or @sideeffect) in the\n"
               "documentation, which will result in a user-defined paragraph with heading\n"
               "\"Side Effects:\". You can put \\n's in the value part of an alias to insert\n"
-              "newlines."
+              "newlines. Note that commands using the \\-syntax have to be escaped, i.e., use\n"
+              "\"\\\\cmd\" instead of \"\\cmd\"."
           );
   doc->add(
               "TCL_SUBST",
diff --git a/doc/commands.doc b/doc/commands.doc
index 912e9ec..60353e5 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -1340,10 +1340,10 @@ class Example
   Where the following aliases are defined in the configuration file:
 
 \verbatim
-ALIASES  = "english=\if english" \
-           "endenglish=\endif" \
-           "dutch=\if dutch" \
-           "enddutch=\endif"
+ALIASES  = "english=\\if english" \
+           "endenglish=\\endif" \
+           "dutch=\\if dutch" \
+           "enddutch=\\endif"
 \endverbatim
 
   and \ref cfg_enabled_sections "ENABLED_SECTIONS" can be used to enable either \c english or \c dutch.
@@ -1735,7 +1735,7 @@ void setPosition(double x,double y,double z,double t)
  configuration file.
  To define a new command \c \\reminder, for instance, one should add the following
  line to the configuration file:
- \verbatim ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim
+ \verbatim ALIASES += "reminder=\\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim
  Note the use of escaped quotes for the second and third argument of the
  \c \\xrefitem command.
 
diff --git a/doc/config.doc b/doc/config.doc
index de563ad..8e3002c 100644
--- a/doc/config.doc
+++ b/doc/config.doc
@@ -633,6 +633,8 @@ The default value is: <code>NO</code>.
  put the command \c \\sideeffect (or \c \@sideeffect) in the documentation, which 
  will result in a user-defined paragraph with heading "Side Effects:".
  You can put \ref cmdn "\\n"'s in the value part of an alias to insert newlines.
+ Note that commands using the \\-syntax have to be escaped, i.e., use "\\\\cmd"
+ instead of "\\cmd".
 
  \anchor cfg_tcl_subst
 <dt>\c TCL_SUBST <dd>
diff --git a/doc/custcmd.doc b/doc/custcmd.doc
index 70d52e4..e6d0093 100644
--- a/doc/custcmd.doc
+++ b/doc/custcmd.doc
@@ -34,13 +34,15 @@ The simplest form of an alias is a simple substitution of the form
 \endverbatim
  For example defining the following alias: 
 \verbatim
- ALIASES += sideeffect="\par Side Effects:\n" 
+ ALIASES += sideeffect="\\par Side Effects:\n" 
 \endverbatim
  will allow you to
  put the command \\sideeffect (or \@sideeffect) in the documentation, which 
  will result in a user-defined paragraph with heading <b>Side Effects:</b>.
 
 Note that you can put \\n's in the value part of an alias to insert newlines.
+Therefore, commands using the \\-syntax need to be escaped, as shown in the
+example above.
 
 Also note that you can redefine existing special commands if you wish.
 
@@ -55,7 +57,7 @@ with 1.
 
 Here is an example of an alias definition with a single argument:
 \verbatim
-ALIASES += l{1}="\ref \1"
+ALIASES += l{1}="\\ref \1"
 \endverbatim
 
 Inside a comment block you can use it as follows
@@ -69,8 +71,8 @@ which would be the same as writing
 
 Note that you can overload an alias by a version with multiple arguments, for instance:
 \verbatim
-ALIASES += l{1}="\ref \1"
-ALIASES += l{2}="\ref \1 \"\2\""
+ALIASES += l{1}="\\ref \1"
+ALIASES += l{2}="\\ref \1 \"\2\""
 \endverbatim
 Note that the quotes inside the alias definition have to be escaped with a backslash.
 
@@ -88,8 +90,8 @@ Aliases can also be expressed in terms of other aliases, e.g. a new command
 \\reminder can be expressed as a \\xrefitem via an intermediate \\xreflist command
 as follows:
 \verbatim
-ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" " \
-ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}" \
+ALIASES += xreflist{3}="\\xrefitem \1 \"\2\" \"\3\" " \
+ALIASES += reminder="\\xreflist{reminders,Reminder,Reminders}" \
 \endverbatim
 
 Note that if for aliases with more than one argument a comma is used as a separator,
diff --git a/src/config.xml b/src/config.xml
index 1174fab..553b237 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -517,6 +517,8 @@ Go to the <a href="commands.html">next</a> section or return to the
  put the command \c \\sideeffect (or \c \@sideeffect) in the documentation, which 
  will result in a user-defined paragraph with heading "Side Effects:".
  You can put \ref cmdn "\\n"'s in the value part of an alias to insert newlines.
+ Note that commands using the \\-syntax have to be escaped, i.e., use "\\\\cmd"
+ instead of "\\cmd".
 ]]>
       </docs>
     </option>
diff --git a/src/configoptions.cpp b/src/configoptions.cpp
index d37163b..279a943 100644
--- a/src/configoptions.cpp
+++ b/src/configoptions.cpp
@@ -329,7 +329,8 @@ void addConfigOptions(Config *cfg)
               "will allow you to put the command \\sideeffect (or @sideeffect) in the\n"
               "documentation, which will result in a user-defined paragraph with heading\n"
               "\"Side Effects:\". You can put \\n's in the value part of an alias to insert\n"
-              "newlines."
+              "newlines. Note that commands using the \\-syntax have to be escaped, i.e., use\n"
+              "\"\\\\cmd\" instead of \"\\cmd\"."
              );
   //----
   cl = cfg->addList(
diff --git a/src/doxygen.cpp b/src/doxygen.cpp
index 8473676..b0107c8 100644
--- a/src/doxygen.cpp
+++ b/src/doxygen.cpp
@@ -9643,22 +9643,28 @@ static void escapeAliases()
   {
     QCString value=*s,newValue;
     int in,p=0;
-    // for each \n in the alias command value
-    while ((in=value.find("\\n",p))!=-1)
+    // for each backslash in the alias command value
+    while ((in=value.find('\\',p))!=-1)
     {
       newValue+=value.mid(p,in-p);
-      // expand \n's except if \n is part of a built-in command.
-      if (value.mid(in,5)!="\\note" && 
-          value.mid(in,5)!="\\name" && 
-          value.mid(in,10)!="\\namespace" && 
-          value.mid(in,14)!="\\nosubgrouping"
-         ) 
+      // assuming that an alias definition cannot end with a backslash
+      char next=value[in+1];
+      if (next=='\\')
+      {
+        newValue+='\\';
+      }
+      else if (next=='n')
       {
         newValue+="\\_linebr ";
       }
-      else 
+      else if (next>='1' && next<='9')
+      {
+        newValue+='\\';
+        newValue+=next;
+      }
+      else
       {
-        newValue+="\\n";
+        err("Unknown escape sequence '\\%c'\n", next);
       }
       p=in+2;
     }
diff --git a/testing/009_bug.cpp b/testing/009_bug.cpp
index 285c77e..ab1bdaf 100644
--- a/testing/009_bug.cpp
+++ b/testing/009_bug.cpp
@@ -9,7 +9,7 @@
 // check: todo.xml
 // check: test.xml
 // check: reminders.xml
-// config: ALIASES = "reminder=\xrefitem reminders \"Reminder\" \"Reminders\""
+// config: ALIASES = "reminder=\\xrefitem reminders \"Reminder\" \"Reminders\""
 
 /** \bug Class bug. */
 class Bug
-- 
1.7.2.5