Merge branch '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

@@ -22,13 +22,56 @@
 #include "qcstring.h"
 #include "construct.h"
 
+class CiteInfoOption
+{
+  public:
+    CiteInfoOption() {}
+    static CiteInfoOption makeNumber()      { return CiteInfoOption(NUMBER); }
+    static CiteInfoOption makeShortAuthor() { return CiteInfoOption(SHORTAUTHOR); }
+    static CiteInfoOption makeYear()        { return CiteInfoOption(YEAR); }
+    void setNoPar()               { m_bits |= NOPAR_BIT; }
+    void setNoCite()              { m_bits |= NOCITE_BIT; }
+
+    bool isUnknown() const        { return (m_bits & TypeMask)==0; }
+    bool isNumber() const         { return (m_bits & NUMBER)!=0; }
+    bool isShortAuthor() const    { return (m_bits & SHORTAUTHOR)!=0; }
+    bool isYear() const           { return (m_bits & YEAR)!=0; }
+
+    bool noPar() const            { return (m_bits & NOPAR_BIT)!=0; }
+    bool noCite() const           { return (m_bits & NOCITE_BIT)!=0; }
+
+    friend inline bool operator==(const CiteInfoOption &t1,const CiteInfoOption &t2) { return t1.m_bits==t2.m_bits; }
+    friend inline bool operator!=(const CiteInfoOption &t1,const CiteInfoOption &t2) { return !(operator==(t1,t2)); }
+
+  private:
+    CiteInfoOption(int bits) : m_bits(bits) {}
+
+    enum Bits
+    {
+      UNKNOWN     = 0,
+      NUMBER      = (1<<0),
+      SHORTAUTHOR = (1<<1),
+      YEAR        = (1<<2),
+
+      TypeMask    = 0x0000FFFF,
+      OptionMask  = 0xFFFF0000,
+
+      NOPAR_BIT   = (1<<16), //< Don't use square brackets
+      NOCITE_BIT  = (1<<17)  //< Don't create a link
+    };
+    unsigned int m_bits = UNKNOWN;
+};
+
+
 /// Citation-related data.
 struct CiteInfo
 {
   ABSTRACT_BASE_CLASS(CiteInfo)
 
   virtual QCString label() const = 0;
   virtual QCString text() const = 0;
+  virtual QCString shortAuthor() const = 0;
+  virtual QCString year() const = 0;
 };
 
 /**

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();
+  auto opt = cite.option();
+  if (!cite.file().isEmpty())
+  {
+    if (!opt.noCite()) startLink(cite.file(),filterId(cite.anchor()));
+
+    filter(cite.getText());
+
+    if (!opt.noCite()) endLink();
+  }
+  else
+  {
+    if (!opt.noPar()) filter("[");
+    filter(cite.target());
+    if (!opt.noPar()) 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 &,CiteInfoOption 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;
+  auto opt = m_option;
+  const CitationManager &ct = CitationManager::instance();
+  const CiteInfo *citeInfo = ct.find(m_target);
+
+  if (!opt.noPar())  txt += "[";
+
+  if (citeInfo)
+  {
+    if      (opt.isNumber())      txt += citeInfo->text();
+    else if (opt.isShortAuthor()) txt += citeInfo->shortAuthor();
+    else if (opt.isYear())        txt += citeInfo->year();
+  }
+
+  if (!opt.noPar()) txt += "]";
+  return txt;
+}
+
+
 //---------------------------------------------------------------------------
 
 DocLink::DocLink(DocParser *parser,DocNodeVariant *parent,const QCString &target) : DocCompoundNode(parser,parent)
@@ -3304,31 +3325,104 @@ 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))
+
+  CiteInfoOption option;
+  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.isUnknown())
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfoOption::makeNumber();
+        }
+      }
+      else if (opt == "year")
+      {
+        if (!option.isUnknown())
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfoOption::makeYear();
+        }
+      }
+      else if (opt == "shortauthor")
+      {
+        if (!option.isUnknown())
+        {
+          warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Multiple options specified with \\{}, discarding '{}'", saveCmdName, opt);
+        }
+        else
+        {
+          option = CiteInfoOption::makeShortAuthor();
+        }
+      }
+      else if (opt == "nopar")
+      {
+        option.setNoPar();
+      }
+      else if (opt == "nocite")
+      {
+        option.setNoCite();
+      }
+      else
+      {
+        warn(parser()->context.fileName,parser()->tokenizer.getLineNr(),"Unkown option specified with \\{}, discarding '{}'", saveCmdName, opt);
+      }
+    }
+
+    if (option.isUnknown()) option = CiteInfoOption::makeNumber();
+
+    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 = CiteInfoOption::makeNumber();
+  }
+
   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();
 }