Merge branch 'feature/bug_cite_option' of https://github.com/albert-github/doxygen into albert-github-feature/bug_cite_option

Author: doxygen

doc/commands.dox

@@ -2477,7 +2477,7 @@ Commands to create links
   \sa section \ref cmdref "\\ref".
 
 <hr>
-\section cmdcite \\cite \<label\>
+\section cmdcite \\cite['{'[option]'}'] \<label\>
 
   \addindex \\cite
   Adds a bibliographic reference in the text and in the list of bibliographic
@@ -2488,6 +2488,18 @@ Commands to create links
   output formats a fixed representation is used. Note that using this
   command requires the \c bibtex tool to be present in the search path.
 
+  There are a number of options possible:
+  - `number`, `shortauthor`, `year`, these options are mutually exclusive,
+    in case none of these is specified `number` is assumed.
+    - `number` create a numerical reference
+    - `shortauthor` just the surname of the first author is given, and in case
+      multiple authors are present the text "et al." is added
+    - `year`, the year of publication is mentioned (when specified in the bibtex
+      file.
+  - `nopar`, no (square) brackets are added
+  - `nocite`, no link to a citation in the bibliography is made (and the
+    reference is not added to the bibliography based on this item)
+
 <hr>
 \section cmdendlink \\endlink
 

src/cite.cpp

@@ -58,16 +58,22 @@ class CiteInfoImpl : public CiteInfo
 {
   public:
     CiteInfoImpl(const QCString &label, const QCString &text=QCString())
-    : m_label(label), m_text(text) { }
+    : m_label(label), m_text(text), m_shortAuthor(QCString()), m_year(QCString()) { }
 
     QCString label() const override { return m_label;    }
     QCString text()  const override { return m_text;     }
+    QCString shortAuthor()  const override { return m_shortAuthor;     }
+    QCString year()  const override { return m_year;     }
 
     void setText(const QCString &s) { m_text = s; }
+    void setShortAuthor(const QCString &s) { m_shortAuthor = s; }
+    void setYear(const QCString &s) { m_year = s; }
 
   private:
     QCString m_label;
     QCString m_text;
+    QCString m_shortAuthor;
+    QCString m_year;
 };
 
 struct CitationManager::Private
@@ -457,20 +463,32 @@ void CitationManager::generatePage()
       if (insideBib && ((i=line.find("name=\"CITEREF_"))!=-1 || (i=line.find("name=\"#CITEREF_"))!=-1))
       {
         int j=line.find("\">[");
-        int k=line.find("]</a>");
+        int j1=line.find("<!--[");
+        int k=line.find("]<!--");
+        int k1=line.find("]-->");
         if (j!=-1 && k!=-1)
         {
           size_t ui=static_cast<size_t>(i);
-          size_t uj=static_cast<size_t>(j);
-          size_t uk=static_cast<size_t>(k);
-          QCString label = line.mid(ui+14,uj-ui-14);
-          QCString number = line.mid(uj+2,uk-uj-1);
-          line = line.left(ui+14) + label + line.right(line.length()-uj);
+          size_t uj0=static_cast<size_t>(j);
+          size_t uj=static_cast<size_t>(j1);
+          size_t uk=static_cast<size_t>(k1);
+          QCString label = line.mid(ui+14,uj0-ui-14);
+          StringVector optList = split(line.mid(uj+5,uk-uj-5).str(),",");
+          QCString number = optList[0].c_str();
+          QCString shortAuthor = optList[1].c_str();
+          QCString year;
+          if (optList.size() == 3)
+          {
+            year = optList[2].c_str();
+          }
+          line = line.left(ui+14) + label + line.right(line.length()-uj0);
           auto it = p->entries.find(label.lower().str());
           //printf("label='%s' number='%s' => %p\n",qPrint(label),qPrint(number),it->second.get());
           if (it!=p->entries.end())
           {
             it->second->setText(number);
+            it->second->setShortAuthor(shortAuthor);
+            it->second->setYear(year.stripWhiteSpace());
           }
         }
       }

src/cite.h

@@ -29,6 +29,18 @@ struct CiteInfo
 
   virtual QCString label() const = 0;
   virtual QCString text() const = 0;
+  virtual QCString shortAuthor() const = 0;
+  virtual QCString year() const = 0;
+
+  enum CiteOptionType {
+    UNKNOWN     = 0x00,
+    NUMBER      = 0x01,
+    SHORTAUTHOR = 0x02,
+    YEAR        = 0x04,
+
+    NOPAR_BIT   = 0x001000, //< Don't use square brackets
+    NOCITE_BIT  = 0x100000, //< Don't create a link
+  };
 };
 
 /**

src/commentscan.l

@@ -3367,15 +3367,22 @@ static bool handleImage(yyscan_t yyscanner,const QCString &s, const StringVector
   return FALSE;
 }
 
-static bool handleCite(yyscan_t yyscanner,const QCString &s, const StringVector &)
+static bool handleCite(yyscan_t yyscanner,const QCString &s, const StringVector &optList)
 {
   struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
   if (!yyextra->spaceBeforeCmd.isEmpty())
   {
     addOutput(yyscanner,yyextra->spaceBeforeCmd);
     yyextra->spaceBeforeCmd.clear();
   }
-  addOutput(yyscanner,"@"+s+" ");
+  if (optList.empty())
+  {
+    addOutput(yyscanner,"@"+s+" ");
+  }
+  else
+  {
+    addOutput(yyscanner,"@"+s+"{"+QCString(join(optList,","))+"} ");
+  }
   BEGIN(CiteLabel);
   return FALSE;
 }

src/docbookvisitor.cpp

@@ -35,6 +35,7 @@
 #include "fileinfo.h"
 #include "portable.h"
 #include "codefragment.h"
+#include "cite.h"
 
 #if 0
 #define DB_VIS_C DB_VIS_C1(m_t)
@@ -602,9 +603,23 @@ void DocbookDocVisitor::operator()(const DocCite &cite)
 {
 DB_VIS_C
   if (m_hide) return;
-  if (!cite.file().isEmpty()) startLink(cite.file(),filterId(cite.anchor()));
-  filter(cite.text());
-  if (!cite.file().isEmpty()) endLink();
+  int opt = cite.option();
+  if (!cite.file().isEmpty())
+  {
+    if (!(opt & CiteInfo::NOCITE_BIT)) startLink(cite.file(),filterId(cite.anchor()));
+
+    filter(cite.getText());
+
+    if (!(opt & CiteInfo::NOCITE_BIT)) endLink();
+  }
+  else
+  {
+    if (!(opt & CiteInfo::NOPAR_BIT)) filter("[");
+    filter(cite.target());
+    if (!(opt & CiteInfo::NOPAR_BIT)) filter("]");
+
+  }
+
 }
 
 //--------------------------------------

src/docnode.cpp

@@ -900,7 +900,7 @@ void DocRef::parse()
 
 //---------------------------------------------------------------------------
 
-DocCite::DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target,const QCString &) : DocNode(parser,parent)
+DocCite::DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target,const QCString &,int opt) : DocNode(parser,parent)
 {
   size_t numBibFiles = Config_getList(CITE_BIB_FILES).size();
   //printf("DocCite::DocCite(target=%s)\n",qPrint(target));
@@ -909,17 +909,17 @@ DocCite::DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target
   const CitationManager &ct = CitationManager::instance();
   const CiteInfo *cite = ct.find(target);
   //printf("cite=%p text='%s' numBibFiles=%d\n",cite,cite?qPrint(cite->text):"<null>",numBibFiles);
+  m_option = opt;
+  m_target = target;
   if (numBibFiles>0 && cite && !cite->text().isEmpty()) // ref to citation
   {
-    m_text         = cite->text();
     m_ref          = "";
     m_anchor       = ct.anchorPrefix()+cite->label();
     m_file         = convertNameToFile(ct.fileName(),FALSE,TRUE);
     //printf("CITE ==> m_text=%s,m_ref=%s,m_file=%s,m_anchor=%s\n",
     //    qPrint(m_text),qPrint(m_ref),qPrint(m_file),qPrint(m_anchor));
     return;
   }
-  m_text = target;
   if (numBibFiles==0)
   {
     warn_doc_error(parser->context.fileName,parser->tokenizer.getLineNr(),"\\cite command found but no bib files specified via CITE_BIB_FILES!");
@@ -936,6 +936,27 @@ DocCite::DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target
   }
 }
 
+QCString DocCite::getText() const
+{
+  QCString txt;
+  int opt = m_option;
+  const CitationManager &ct = CitationManager::instance();
+  const CiteInfo *citeInfo = ct.find(m_target);
+
+  if (!(opt & CiteInfo::NOPAR_BIT))  txt += "[";
+
+  if (citeInfo)
+  {
+    if (opt & CiteInfo::NUMBER)  txt += citeInfo->text();
+    else if (opt & CiteInfo::SHORTAUTHOR)  txt += citeInfo->shortAuthor();
+    else if (opt & CiteInfo::YEAR)  txt += citeInfo->year();
+  }
+
+  if (!(opt & CiteInfo::NOPAR_BIT)) txt += "]";
+  return txt;
+}
+
+
 //---------------------------------------------------------------------------
 
 DocLink::DocLink(DocParser *parser,DocNodeVariant *parent,const QCString &target) : DocCompoundNode(parser,parent)
@@ -3304,31 +3325,102 @@ Token DocPara::handleParamSection(const QCString &cmdName,
 void DocPara::handleCite(char cmdChar,const QCString &cmdName)
 {
   AUTO_TRACE();
+  QCString saveCmdName = cmdName;
   // get the argument of the cite command.
   Token tok=parser()->tokenizer.lex();
-  if (!tok.is(TokenRetval::TK_WHITESPACE))
+
+  int option = CiteInfo::UNKNOWN;
+  bool nopar_bit = false;
+  bool nocite_bit = false;
+  if (tok.is(TokenRetval::TK_WORD) && parser()->context.token->name=="{")
+  {
+    parser()->tokenizer.setStateOptions();
+    parser()->tokenizer.lex();
+    StringVector optList=split(parser()->context.token->name.str(),",");
+    for (auto const &opt : optList)
+    {
+      if (opt == "number")
+      {
+        if (option != CiteInfo::UNKNOWN)
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfo::NUMBER;
+        }
+      }
+      else if (opt == "year")
+      {
+        if (option != CiteInfo::UNKNOWN)
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfo::YEAR;
+        }
+      }
+      else if (opt == "shortauthor")
+      {
+        if (option != CiteInfo::UNKNOWN)
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfo::SHORTAUTHOR;
+        }
+      }
+      else if (opt == "nopar")  nopar_bit = true;
+      else if (opt == "nocite") nocite_bit = true;
+      else
+      {
+        warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Unkown option specified with \\{}, discarding '{}'", saveCmdName, opt);
+      }
+    }
+
+    if (option == CiteInfo::UNKNOWN) option = CiteInfo::NUMBER;
+    if (nopar_bit) option |= CiteInfo::NOPAR_BIT;
+    if (nocite_bit) option |= CiteInfo::NOCITE_BIT;
+
+    parser()->tokenizer.setStatePara();
+    tok=parser()->tokenizer.lex();
+    if (!tok.is(TokenRetval::TK_WHITESPACE))
+    {
+      warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),"expected whitespace after \\{} command",
+          saveCmdName);
+      return;
+    }
+  }
+  else if (!tok.is(TokenRetval::TK_WHITESPACE))
   {
     warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),"expected whitespace after '{:c}{}' command",
-      cmdChar,cmdName);
+      cmdChar,saveCmdName);
     return;
   }
+  else
+  {
+    option = CiteInfo::NUMBER;
+  }
+
   parser()->tokenizer.setStateCite();
   tok=parser()->tokenizer.lex();
   if (tok.is_any_of(TokenRetval::TK_NONE,TokenRetval::TK_EOF))
   {
-    warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),"unexpected end of comment block while parsing the "
-        "argument of command '{:c}{}'",cmdChar,cmdName);
+    warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),"THE ONE unexpected end of comment block while parsing the "
+        "argument of command '{:c}{}'",cmdChar,saveCmdName);
     return;
   }
   else if (!tok.is_any_of(TokenRetval::TK_WORD,TokenRetval::TK_LNKWORD))
   {
     warn_doc_error(parser()->context.fileName,parser()->tokenizer.getLineNr(),"unexpected token {} as the argument of '{:c}{}'",
-        tok.to_string(),cmdChar,cmdName);
+        tok.to_string(),cmdChar,saveCmdName);
     return;
   }
   parser()->context.token->sectionId = parser()->context.token->name;
   children().append<DocCite>(
-        parser(),thisVariant(),parser()->context.token->name,parser()->context.context);
+        parser(),thisVariant(),parser()->context.token->name,parser()->context.context,option);
 
   parser()->tokenizer.setStatePara();
 }

src/docnode.h

@@ -243,19 +243,22 @@ class DocAnchor : public DocNode
 class DocCite : public DocNode
 {
   public:
-    DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target,const QCString &context);
+    DocCite(DocParser *parser,DocNodeVariant *parent,const QCString &target,const QCString &context, int opt);
     QCString file() const        { return m_file; }
     QCString relPath() const     { return m_relPath; }
     QCString ref() const         { return m_ref; }
     QCString anchor() const      { return m_anchor; }
-    QCString text() const        { return m_text; }
+    QCString target() const      { return m_target; }
+    int option() const           { return m_option; }
+    QCString getText() const;
 
   private:
     QCString   m_file;
     QCString   m_relPath;
     QCString   m_ref;
     QCString   m_anchor;
-    QCString   m_text;
+    QCString   m_target;
+    int        m_option;
 };