Added internal \iprefix to add the prefer to \ref and \link as well

doxygen · Mar 31, 2024 · fc71d18 · fc71d18
1 parent 068ee88
commit fc71d18
Show file tree

Hide file tree

Showing 12 changed files with 112 additions and 20 deletions.
diff --git a/doc_internal/commands_internal.md b/doc_internal/commands_internal.md
@@ -14,6 +14,7 @@ and the version in which they were introduced.
 \refitem cmdiline \\iline
 \refitem cmdilinebr \\ilinebr
 \refitem cmdiliteral \\iliteral
+\refitem cmdiprefix \\iprefix
 \refitem cmdiraise \\iraise
 \refitem cmdiverbatim \\iverbatim
 \endsecreflist
@@ -130,13 +131,23 @@ and the version in which they were introduced.
 \since doxygen version 1.9.5
 
 <hr>
-\section cmdiraise \\iraise \<amount\> "<label>"
+\section cmdiraise \\iraise \<amount\>
   \addindex \\iraise
 
-  Internal doxygen command to increase the section level by a given `amount` and append the
-  `label` to the label of the `\section` type of commands and the the `\anchor` command.
-  After processing `\iraise 1 "_lab"` for instance, a `\section s1` will be treated as a `\subsection s1_lab`.
-  Inserted when processing `\include{doc}` with the `raise` or `label` option.
+  Internal doxygen command to increase the section level by a given `amount`.
+  After processing `\iraise 1` for instance, a `\section s1` will be treated as a `\subsection s1`.
+  Inserted when processing `\include{doc}` with the `raise` option.
+
+\since doxygen version 1.11.0
+
+<hr>
+\section cmdiprefix \\iprefix "<label>"
+  \addindex \\iprefix
+
+  Internal doxygen command to prefix section labels references for \c \\ref and \c \\link commands.
+  After processing `\iprefix "pf_"` for instance, a <code>\\ref s1</code> will be treated as 
+  if <code>\\ref pf_s1</code> was written.
+  Inserted internally when processing `\include{doc}` with the `prefix` option.
 
 \since doxygen version 1.11.0
 

diff --git a/src/cmdmapper.cpp b/src/cmdmapper.cpp
@@ -155,6 +155,7 @@ static const CommandMap g_cmdMap =
   { "iliteral",      CMD_ILITERAL },
   { "endiliteral",   CMD_ENDILITERAL },
   { "ianchor" ,      CMD_IANCHOR },
+  { "iprefix" ,      CMD_IPREFIX },
 };
 
 //----------------------------------------------------------------------------

diff --git a/src/cmdmapper.h b/src/cmdmapper.h
@@ -156,7 +156,8 @@ enum CommandType
   CMD_DOXYCONFIG   = 126,
   CMD_IMPORTANT    = 127 | SIMPLESECT_BIT,
   CMD_SUBPARAGRAPH = 128,
-  CMD_SUBSUBPARAGRAPH = 129
+  CMD_SUBSUBPARAGRAPH = 129,
+  CMD_IPREFIX      = 130
 };
 
 enum HtmlTagType

diff --git a/src/commentcnv.l b/src/commentcnv.l
@@ -1286,9 +1286,13 @@ SLASHopt [/]*
                                        yyextra->inBufPos      = fs->oldFileBufPos;
                                        yyextra->includeCtx    = fs->oldIncludeCtx;
                                        QCString lineStr= " \\ilinebr \\ifile \""+yyextra->fileName+"\" \\iline "+QCString().setNum(yyextra->lineNr)+" ";
-                                       if (fs->oldRaiseLvl!=yyextra->raiseLevel || fs->oldRaiseLbl!=yyextra->raiseLabel)
+                                       if (fs->oldRaiseLvl!=yyextra->raiseLevel)
                                        {
-                                          lineStr+=" \\iraise " + std::to_string(fs->oldRaiseLvl) + " \"" + fs->oldRaiseLbl + "\"";
+                                          lineStr+=" \\iraise " + std::to_string(fs->oldRaiseLvl);
+                                       }
+                                       if (fs->oldRaiseLbl!=yyextra->raiseLabel)
+                                       {
+                                          lineStr+=" \\iprefix \"" + fs->oldRaiseLbl + "\"";
                                        }
                                        yyextra->raiseLevel    = fs->oldRaiseLvl;
                                        yyextra->raiseLabel    = fs->oldRaiseLbl;
@@ -1687,9 +1691,13 @@ static bool readIncludeFile(yyscan_t yyscanner,const QCString &inc,const QCStrin
     yyextra->raiseLevel+=yyextra->raiseIncrement;
     yyextra->raiseLabel+=yyextra->raisePrefix;
     QCString lineStr=" \\ilinebr \\ifile \""+absFileName+"\" \\iline " + std::to_string(lineNr);
-    if (yyextra->raiseLevel>0 || !yyextra->raiseLabel.isEmpty())
+    if (yyextra->raiseLevel>0)
+    {
+      lineStr+=" \\iraise " + std::to_string(yyextra->raiseLevel);
+    }
+    if (!yyextra->raiseLabel.isEmpty())
     {
-      lineStr+=" \\iraise " + std::to_string(yyextra->raiseLevel) + " \"" + yyextra->raiseLabel + "\"";
+      lineStr+=" \\iprefix \"" + yyextra->raiseLabel + "\"";
     }
     lineStr+=" \\ilinebr ";
     copyToOutput(yyscanner,lineStr.view());

diff --git a/src/commentscan.l b/src/commentscan.l
@@ -170,6 +170,7 @@ static bool handleModule(yyscan_t yyscanner,const QCString &, const StringVector
 static bool handleIFile(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleILine(yyscan_t yyscanner,const QCString &, const StringVector &);
 static bool handleIRaise(yyscan_t yyscanner,const QCString &, const StringVector &);
+static bool handleIPrefix(yyscan_t yyscanner,const QCString &, const StringVector &);
 
 [[maybe_unused]] static const char *stateToString(int state);
 
@@ -396,7 +397,8 @@ static const std::map< std::string, DocCmdMap > docCmdMap =
   { "endlink",                { 0,                               CommandSpacing::Invisible, SectionHandling::Escape  }},
   { "ifile",                  { &handleIFile,                    CommandSpacing::Invisible, SectionHandling::Replace }},
   { "iline",                  { &handleILine,                    CommandSpacing::Invisible, SectionHandling::Replace }},
-  { "iraise",                 { &handleIRaise,                   CommandSpacing::Invisible, SectionHandling::Replace }}
+  { "iraise",                 { &handleIRaise,                   CommandSpacing::Invisible, SectionHandling::Replace }},
+  { "iprefix",                { &handleIPrefix,                  CommandSpacing::Invisible, SectionHandling::Replace }}
 };
 
 #define YY_NO_INPUT 1
@@ -1763,18 +1765,21 @@ STopt  [^\n@\\]*
                                           {
                                             yyextra->raiseLevel = nr;
                                           }
-                                          BEGIN(IRaisePrefix);
+                                          BEGIN(Comment);
                                         }
 <IRaise>.                               {
                                           unput(yytext[0]);
                                           BEGIN(Comment);
                                         }
-<IRaisePrefix>{B}*"\""({LABELID})?"\""   {
+  /* ----- handle arguments of the iprefix command ----- */
+
+<IRaisePrefix>{B}*"\""({LABELID})?"\""  {
                                           QCString text(yytext);
                                           yyextra->raisePrefix = text.stripWhiteSpace().mid(1,text.length()-2);
+                                          addOutput(yyscanner,yytext);
                                           BEGIN(Comment);
                                         }
-<IRaisePrefix>.                          {
+<IRaisePrefix>.                         {
                                           unput(yytext[0]);
                                           BEGIN(Comment);
                                         }
@@ -3468,6 +3473,13 @@ static bool handleIRaise(yyscan_t yyscanner,const QCString &, const StringVector
   return FALSE;
 }
 
+static bool handleIPrefix(yyscan_t yyscanner,const QCString &, const StringVector &)
+{
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  addOutput(yyscanner,"@iprefix ");
+  BEGIN(IRaisePrefix);
+  return FALSE;
+}
 
 static bool handleIf(yyscan_t yyscanner,const QCString &, const StringVector &)
 {

diff --git a/src/docnode.cpp b/src/docnode.cpp
@@ -694,7 +694,7 @@ DocRef::DocRef(DocParser *parser,DocNodeVariant *parent,const QCString &target,c
   ASSERT(!target.isEmpty());
   SrcLangExt lang = getLanguageFromFileName(target);
   m_relPath = parser->context.relPath;
-  const SectionInfo *sec = SectionManager::instance().find(target);
+  const SectionInfo *sec = SectionManager::instance().find(parser->context.prefix+target);
   if (sec==nullptr && lang==SrcLangExt::Markdown) // lookup as markdown file
   {
     sec = SectionManager::instance().find(markdownFileNameToId(target));
@@ -731,7 +731,7 @@ DocRef::DocRef(DocParser *parser,DocNodeVariant *parent,const QCString &target,c
     //    qPrint(m_text),qPrint(m_ref),qPrint(m_file),m_refType);
     return;
   }
-  else if (resolveLink(context,target,TRUE,&compound,anchor))
+  else if (resolveLink(context,target,TRUE,&compound,anchor,parser->context.prefix))
   {
     bool isFile = compound ?
                  (compound->definitionType()==Definition::TypeFile ||
@@ -911,7 +911,7 @@ DocLink::DocLink(DocParser *parser,DocNodeVariant *parent,const QCString &target
   {
     m_refText = m_refText.right(m_refText.length()-1);
   }
-  if (resolveLink(parser->context.context,stripKnownExtensions(target),parser->context.inSeeBlock,&compound,anchor))
+  if (resolveLink(parser->context.context,stripKnownExtensions(target),parser->context.inSeeBlock,&compound,anchor,parser->context.prefix))
   {
     m_anchor = anchor;
     if (compound && compound->isLinkable())
@@ -4370,6 +4370,11 @@ int DocPara::handleCommand(char cmdChar, const QCString &cmdName)
         parser()->handleAnchor(thisVariant(),children());
       }
       break;
+    case CMD_IPREFIX:
+      {
+        parser()->handlePrefix(thisVariant(),children());
+      }
+      break;
     case CMD_ADDINDEX:
       {
         children().append<DocIndexEntry>(parser(),thisVariant(),

diff --git a/src/docparser.cpp b/src/docparser.cpp
@@ -958,6 +958,33 @@ void DocParser::handleAnchor(DocNodeVariant *parent,DocNodeList &children)
   children.append<DocAnchor>(this,parent,context.token->name,FALSE);
 }
 
+void DocParser::handlePrefix(DocNodeVariant *parent,DocNodeList &children)
+{
+  AUTO_TRACE();
+  int tok=tokenizer.lex();
+  if (tok!=TK_WHITESPACE)
+  {
+    warn_doc_error(context.fileName,tokenizer.getLineNr(),"expected whitespace after \\%s command",
+        qPrint(context.token->name));
+    return;
+  }
+  tokenizer.setStatePrefix();
+  tok=tokenizer.lex();
+  if (tok==0)
+  {
+    warn_doc_error(context.fileName,tokenizer.getLineNr(),"unexpected end of comment block while parsing the "
+        "argument of command %s",qPrint(context.token->name));
+    return;
+  }
+  else if (tok!=TK_WORD)
+  {
+    warn_doc_error(context.fileName,tokenizer.getLineNr(),"unexpected token %s as the argument of %s",
+        DocTokenizer::tokToString(tok),qPrint(context.token->name));
+    return;
+  }
+  context.prefix = context.token->name;
+  tokenizer.setStatePara();
+}
 
 /* Helper function that deals with the title, width, and height arguments of various commands.
  * @param[in] cmd        Command id for which to extract caption and size info.
@@ -1347,6 +1374,11 @@ bool DocParser::defaultHandleToken(DocNodeVariant *parent,int tok, DocNodeList &
             handleAnchor(parent,children);
           }
           break;
+        case CMD_IPREFIX:
+          {
+            handlePrefix(parent,children);
+          }
+          break;
         case CMD_INTERNALREF:
           {
             handleInternalRef(parent,children);

diff --git a/src/docparser_p.h b/src/docparser_p.h
@@ -76,6 +76,7 @@ struct DocParserContext
   bool         isExample = false;
   QCString     exampleName;
   QCString     searchUrl;
+  QCString     prefix;
 
   QCString     includeFileName;
   QCString     includeFileText;
@@ -128,6 +129,7 @@ class DocParser : public IDocParser
     void handleParameterType(DocNodeVariant *parent,DocNodeList &children,const QCString &paramTypes);
     void handleInternalRef(DocNodeVariant *parent,DocNodeList &children);
     void handleAnchor(DocNodeVariant *parent,DocNodeList &children);
+    void handlePrefix(DocNodeVariant *parent,DocNodeList &children);
     void handleImage(DocNodeVariant *parent, DocNodeList &children);
     void readTextFileByName(const QCString &file,QCString &text);
 

diff --git a/src/doctokenizer.h b/src/doctokenizer.h
@@ -187,6 +187,7 @@ class DocTokenizer
     void setStateILine();
     void setStateQuotedString();
     void setStateShowDate();
+    void setStatePrefix();
 
   private:
     struct Private;

diff --git a/src/doctokenizer.l b/src/doctokenizer.l
@@ -386,6 +386,7 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
 %x St_Text
 %x St_SkipTitle
 %x St_Anchor
+%x St_Prefix
 %x St_Snippet
 %x St_SetScope
 %x St_SetScopeEnd
@@ -1270,6 +1271,15 @@ SHOWDATE ([0-9]{4}"-"[0-9]{1,2}"-"[0-9]{1,2})?({WS}*[0-9]{1,2}":"[0-9]{1,2}(":"[
                          yyextra->token.chars=yytext;
                          return TK_WHITESPACE;
                        }
+<St_Prefix>"\""[^\n\"]*"\"" {
+                         yyextra->token.name = yytext+1;
+                         yyextra->token.name = yyextra->token.name.left((int)yyleng-2);
+                         return TK_WORD;
+                       }
+<St_Prefix>.           {
+                         unput(*yytext);
+                         return 0;
+                       }
 <St_Options>{ID}       {
                          yyextra->token.name+=yytext;
                        }
@@ -2079,6 +2089,13 @@ void DocTokenizer::setStateAnchor()
   BEGIN(St_Anchor);
 }
 
+void DocTokenizer::setStatePrefix()
+{
+  yyscan_t yyscanner = p->yyscanner;
+  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
+  BEGIN(St_Prefix);
+}
+
 void DocTokenizer::setStateSnippet()
 {
   yyscan_t yyscanner = p->yyscanner;

diff --git a/src/util.cpp b/src/util.cpp
@@ -3061,7 +3061,8 @@ bool resolveLink(/* in */ const QCString &scName,
     /* in */ const QCString &lr,
     /* in */ bool /*inSeeBlock*/,
     /* out */ const Definition **resContext,
-    /* out */ QCString &resAnchor
+    /* out */ QCString &resAnchor,
+    /* in */ const QCString &prefix
     )
 {
   *resContext=nullptr;
@@ -3097,7 +3098,7 @@ bool resolveLink(/* in */ const QCString &scName,
     }
     return TRUE;
   }
-  else if ((si=SectionManager::instance().find(linkRef)))
+  else if ((si=SectionManager::instance().find(prefix+linkRef)))
   {
     *resContext=si->definition();
     resAnchor = si->label();

diff --git a/src/util.h b/src/util.h
@@ -144,7 +144,8 @@ bool resolveLink(/* in */  const QCString &scName,
                  /* in */  const QCString &lr,
                  /* in */  bool inSeeBlock,
                  /* out */ const Definition **resContext,
-                 /* out */ QCString &resAnchor
+                 /* out */ QCString &resAnchor,
+                 /* in */  const QCString &prefix=QCString()
                 );
 
 bool generateLink(OutputList &ol,const QCString &,