From 7506404e646f1fcc5a26ca6fca91a7f65154f05a Mon Sep 17 00:00:00 2001 From: Dimitri van Heesch Date: Sun, 10 Aug 2014 20:09:33 +0200 Subject: Bug 731947 - Support for PlantUML --- Doxyfile | 48 ++++++++++++++---------- doc/commands.doc | 61 +++++++++++++++++++++++++++++++ src/cmdmapper.cpp | 2 + src/cmdmapper.h | 4 +- src/commentcnv.l | 6 +-- src/commentscan.l | 16 ++++++-- src/compound.xsd | 2 +- src/config.l | 31 ++++++++++++++++ src/config.xml | 10 +++++ src/docbookvisitor.cpp | 94 +++++++++++++++++++++++++++++++++-------------- src/docbookvisitor.h | 1 + src/docparser.cpp | 18 +++++++++ src/docparser.h | 2 +- src/doctokenizer.h | 1 + src/doctokenizer.l | 32 +++++++++++++++- src/htmldocvisitor.cpp | 48 +++++++++++++++++++++++- src/htmldocvisitor.h | 1 + src/htmlentity.cpp | 2 +- src/latexdocvisitor.cpp | 29 +++++++++++++++ src/latexdocvisitor.h | 1 + src/libdoxygen.pro.in | 2 + src/mandocvisitor.cpp | 1 + src/markdown.cpp | 4 ++ src/perlmodgen.cpp | 3 +- src/plantuml.cpp | 97 +++++++++++++++++++++++++++++++++++++++++++++++++ src/plantuml.h | 40 ++++++++++++++++++++ src/printdocvisitor.h | 2 + src/rtfdocvisitor.cpp | 34 ++++++++++++++++- src/rtfdocvisitor.h | 1 + src/xmldocvisitor.cpp | 5 +++ winbuild/Doxygen.vcproj | 8 ++++ 31 files changed, 544 insertions(+), 62 deletions(-) create mode 100644 src/plantuml.cpp create mode 100644 src/plantuml.h diff --git a/Doxyfile b/Doxyfile index bc30271..325a875 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.3.1 +# Doxyfile 1.8.7 #--------------------------------------------------------------------------- # Project related configuration options @@ -10,6 +10,7 @@ PROJECT_BRIEF = PROJECT_LOGO = OUTPUT_DIRECTORY = doxygen_docs CREATE_SUBDIRS = YES +ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES @@ -63,6 +64,7 @@ INTERNAL_DOCS = NO CASE_SENSE_NAMES = NO HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = NO INLINE_INFO = YES SORT_MEMBER_DOCS = YES @@ -84,7 +86,7 @@ FILE_VERSION_FILTER = LAYOUT_FILE = CITE_BIB_FILES = #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES @@ -94,9 +96,10 @@ WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text " WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = src +INPUT = src \ + vhdlparser INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h \ *.cpp \ @@ -105,6 +108,7 @@ RECURSIVE = NO EXCLUDE = src/logos.cpp \ src/lodepng.cpp EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = EXCLUDE_SYMBOLS = EXAMPLE_PATH = EXAMPLE_PATTERNS = @@ -116,7 +120,7 @@ FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- SOURCE_BROWSER = YES INLINE_SOURCES = NO @@ -124,18 +128,17 @@ STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES USE_HTAGS = NO VERBATIM_HEADERS = YES -CLANG_ASSISTED_PARSING = YES -CLANG_OPTIONS = #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = @@ -184,6 +187,7 @@ USE_MATHJAX = NO MATHJAX_FORMAT = HTML-CSS MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = SEARCHENGINE = YES SERVER_BASED_SEARCH = YES EXTERNAL_SEARCH = NO @@ -192,7 +196,7 @@ SEARCHDATA_FILE = searchdata.xml EXTERNAL_SEARCH_ID = EXTRA_SEARCH_MAPPINGS = #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- GENERATE_LATEX = NO LATEX_OUTPUT = @@ -211,7 +215,7 @@ LATEX_HIDE_INDICES = NO LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- GENERATE_RTF = NO RTF_OUTPUT = @@ -220,31 +224,31 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- GENERATE_MAN = NO MAN_OUTPUT = MAN_EXTENSION = .3 +MAN_SUBDIR = MAN_LINKS = NO #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- -# configuration options related to the DOCBOOK output +# Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- GENERATE_PERLMOD = NO PERLMOD_LATEX = NO @@ -257,13 +261,14 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES -INCLUDE_PATH = qtools libmd5 +INCLUDE_PATH = qtools \ + libmd5 INCLUDE_FILE_PATTERNS = PREDEFINED = EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- TAGFILES = qtools_docs/qtools.tag=../../qtools_docs/html GENERATE_TAGFILE = doxygen.tag @@ -276,6 +281,7 @@ PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- CLASS_DIAGRAMS = NO MSCGEN_PATH = +DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES DOT_NUM_THREADS = 0 @@ -299,6 +305,8 @@ INTERACTIVE_SVG = YES DOT_PATH = DOTFILE_DIRS = MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO diff --git a/doc/commands.doc b/doc/commands.doc index 9175856..73eb842 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -90,6 +90,7 @@ documentation: \refitem cmdendrtfonly \\endrtfonly \refitem cmdendsecreflist \\endsecreflist \refitem cmdendverbatim \\endverbatim +\refitem cmdenduml \\enduml \refitem cmdendxmlonly \\endxmlonly \refitem cmdenum \\enum \refitem cmdexample \\example @@ -174,6 +175,7 @@ documentation: \refitem cmdskip \\skip \refitem cmdskipline \\skipline \refitem cmdsnippet \\snippet +\refitem cmdstartuml \\startuml \refitem cmdstruct \\struct \refitem cmdsubpage \\subpage \refitem cmdsubsection \\subsection @@ -2531,6 +2533,59 @@ class Receiver \sa section \ref cmdmscfile "\\mscfile".
+\section cmdstartuml \\startuml + + \addindex \\startuml + Starts a text fragment which should contain a valid description of a + PlantUML diagram. See http://plantuml.sourceforge.net/ for examples. + The text fragment ends with \ref cmdenduml "\\enduml". + \note You need to install Java and the PlantUML's jar file, + if you want to use this command. The location of the jar file should be specified + using \ref cfg_plantuml_jar_path "PLANTUML_JAR_PATH". + +Here is an example of the use of the \c \\startuml command. +\code +/** Sender class. Can be used to send a command to the server. + * The receiver will acknowledge the command by calling Ack(). + * \startuml + * Sender->Receiver : Command() + * Sender<--Receiver : Ack() + * \enduml + */ +class Sender +{ + public: + /** Acknowledgment from server */ + void Ack(bool ok); +}; + +/** Receiver class. Can be used to receive and execute commands. + * After execution of a command, the receiver will send an acknowledgment + * \startuml + * Receiver<-Sender : Command() + * Receiver-->Sender : Ack() + * \enduml + */ +class Receiver +{ + public: + /** Executable a command on the server */ + void Command(int commandId); +}; +\endcode + +\note For compatibility with running PlantUML as a preprocessing step before +running doxygen, you can also add the name of the image file after \c \\startuml +and inside curly brackets, i.e. +\verbatim +@startuml{myimage.png} +Alice -> Bob : Hello +@enduml +\endverbatim +When the name of the image is specified, doxygen will generate an image with that name. +Without the name doxygen will choose a name automatically. + +
\section cmddotfile \\dotfile ["caption"] \addindex \\dotfile @@ -2651,6 +2706,12 @@ class Receiver Ends a block that was started with \ref cmdmsc "\\msc".
+\section cmdenduml \\enduml + + \addindex \\enduml + Ends a block that was started with \ref cmdstartuml "\\startuml". + +
\section cmdendhtmlonly \\endhtmlonly \addindex \\endhtmlonly diff --git a/src/cmdmapper.cpp b/src/cmdmapper.cpp index 45469f2..b0ca85f 100644 --- a/src/cmdmapper.cpp +++ b/src/cmdmapper.cpp @@ -120,8 +120,10 @@ CommandMap cmdMap[] = { "_internalref", CMD_INTERNALREF }, { "dot", CMD_DOT }, { "msc", CMD_MSC }, + { "startuml", CMD_STARTUML }, { "enddot", CMD_ENDDOT }, { "endmsc", CMD_ENDMSC }, + { "enduml", CMD_ENDUML }, { "manonly", CMD_MANONLY }, { "endmanonly", CMD_ENDMANONLY }, { "includelineno", CMD_INCWITHLINES }, diff --git a/src/cmdmapper.h b/src/cmdmapper.h index d89e368..75fd8ec 100644 --- a/src/cmdmapper.h +++ b/src/cmdmapper.h @@ -127,7 +127,9 @@ enum CommandType CMD_DIAFILE = 97, CMD_LATEXINCLUDE = 98, CMD_NDASH = 99, - CMD_MDASH = 100 + CMD_MDASH = 100, + CMD_STARTUML = 101, + CMD_ENDUML = 102 }; enum HtmlTagType diff --git a/src/commentcnv.l b/src/commentcnv.l index 4cc9da9..ec56b90 100644 --- a/src/commentcnv.l +++ b/src/commentcnv.l @@ -446,7 +446,7 @@ void replaceComment(int offset); g_blockName=&yytext[1]; BEGIN(VerbatimCode); } -[\\@]("dot"|"code"|"msc")/[^a-z_A-Z0-9] { /* start of a verbatim block */ +[\\@]("dot"|"code"|"msc"|"startuml")/[^a-z_A-Z0-9] { /* start of a verbatim block */ copyToOutput(yytext,(int)yyleng); g_lastCommentContext = YY_START; g_javaBlock=0; @@ -517,7 +517,7 @@ void replaceComment(int offset); } } } -[\\@]("enddot"|"endcode"|"endmsc") { /* end of verbatim block */ +[\\@]("enddot"|"endcode"|"endmsc"|"enduml") { /* end of verbatim block */ copyToOutput(yytext,(int)yyleng); if (&yytext[4]==g_blockName) { @@ -554,7 +554,7 @@ void replaceComment(int offset); copyToOutput(yytext,(int)yyleng); } ^[ \t]*"///" { - if (g_blockName=="dot" || g_blockName=="msc" || g_blockName.at(0)=='f') + if (g_blockName=="dot" || g_blockName=="msc" || g_blockName=="startuml" || g_blockName.at(0)=='f') { // see bug 487871, strip /// from dot images and formulas. int l=0; diff --git a/src/commentscan.l b/src/commentscan.l index a42f6ce..369349b 100644 --- a/src/commentscan.l +++ b/src/commentscan.l @@ -191,6 +191,7 @@ static DocCmdMap docCmdMap[] = { "manonly", &handleFormatBlock, FALSE }, { "dot", &handleFormatBlock, TRUE }, { "msc", &handleFormatBlock, TRUE }, + { "startuml", &handleFormatBlock, TRUE }, { "code", &handleFormatBlock, TRUE }, { "addindex", &handleAddIndex, FALSE }, { "if", &handleIf, FALSE }, @@ -877,7 +878,7 @@ static int yyread(char *buf,int max_size) /* start command character */ CMD ("\\"|"@") DCMD1 ("arg"|"attention"|"author"|"cite"|"code") -DCMD2 ("date"|"dot"|"msc"|"dotfile"|"example") +DCMD2 ("date"|"dot"|"msc"|"dotfile"|"example"|"startuml") DCMD3 ("htmlinclude"|"htmlonly"|"image"|"include") DCMD4 ("includelineno"|"internal"|"invariant") DCMD5 ("latexinclude"|"latexonly"|"li"|"line"|"manonly"|"name") @@ -1785,6 +1786,13 @@ RCSTAG "$"{ID}":"[^\n$]+"$" BEGIN(Comment); } } +{CMD}"enduml" { + addOutput(yytext); + if (blockName=="startuml") // found end of the block + { + BEGIN(Comment); + } + } [^ \@\*\/\\\n]* { // some word addOutput(yytext); } @@ -1809,9 +1817,11 @@ RCSTAG "$"{ID}":"[^\n$]+"$" addOutput(*yytext); } <> { + QCString endTag = "@end"+blockName; + if (blockName=="startuml") endTag="enduml"; warn(yyFileName,yyLineNr, - "reached end of comment while inside a @%s block; check for missing @end%s tag!", - blockName.data(),blockName.data() + "reached end of comment while inside a @%s block; check for missing @%s tag!", + blockName.data(),endTag.data() ); yyterminate(); } diff --git a/src/compound.xsd b/src/compound.xsd index dec596b..be897c3 100644 --- a/src/compound.xsd +++ b/src/compound.xsd @@ -386,7 +386,7 @@ - + diff --git a/src/config.l b/src/config.l index 133bc11..a237faf 100644 --- a/src/config.l +++ b/src/config.l @@ -1329,6 +1329,37 @@ void Config::check() mscgenPath=""; } + // check plantuml path + QCString &plantumlJarPath = Config_getString("PLANTUML_JAR_PATH"); + if (!plantumlJarPath.isEmpty()) + { + QFileInfo pu(plantumlJarPath); + if (pu.exists() && pu.isDir()) // PLANTUML_JAR_PATH is directory + { + QFileInfo jar(plantumlJarPath+portable_pathSeparator()+"plantuml.jar"); + if (jar.exists() && jar.isFile()) + { + plantumlJarPath = jar.dirPath(TRUE).utf8()+portable_pathSeparator(); + } + else + { + config_err("Jar file plantuml.jar not found at location " + "specified via PLANTUML_JAR_PATH: '%s'\n",plantumlJarPath.data()); + plantumlJarPath=""; + } + } + else if (pu.exists() && pu.isFile() && plantumlJarPath.right(4)==".jar") // PLANTUML_JAR_PATH is file + { + plantumlJarPath = pu.dirPath(TRUE).utf8()+portable_pathSeparator(); + } + else + { + config_err("path specified via PLANTUML_JAR_PATH does not exist or not a directory: %s\n", + plantumlJarPath.data()); + plantumlJarPath=""; + } + } + // check dia path QCString &diaPath = Config_getString("DIA_PATH"); if (!diaPath.isEmpty()) diff --git a/src/config.xml b/src/config.xml index 5a0af59..9020d30 100644 --- a/src/config.xml +++ b/src/config.xml @@ -3295,6 +3295,16 @@ to be found in the default search path. ]]> + + + @@ -2615,6 +2619,10 @@ > + + -- cgit v0.12