Initial commit.

.dir-locals.el

@@ -0,0 +1,10 @@
+;;; Directory Local Variables
+;;; See Info node `(emacs) Directory Variables' for more information.
+
+((nil .
+      ((indent-tabs-mode . nil)))
+ (c++-mode .
+	   ((c-file-style . "stroustrup")
+	    (c-basic-offset . 4)
+	    (tab-width . 4)
+	    (show-trailing-whitespace . t))))

.gitignore

@@ -0,0 +1,2 @@
+*.a
+*.so

LICENSE

@@ -0,0 +1,26 @@
+Copyright © 2019 Marvin Gülker
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above
+   copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided
+   with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,53 @@
+# Copyright © 2019 Marvin Gülker
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above
+#    copyright notice, this list of conditions and the following
+#    disclaimer in the documentation and/or other materials provided
+#    with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+# OF THE POSSIBILITY OF SUCH DAMAGE.
+
+CC           := cc
+CFLAGS       := -std=c++11 -Wall -Wextra
+SHAREDCFLAGS := -shared -fPIC
+DESTDIR      := /usr/local
+
+all: libpod-cpp.a libpod-cpp.so
+
+clean:
+	rm -f libpod-cpp.a
+	rm -f libpod-cpp.so
+
+install: libpod-cpp.a libpod-cpp.so
+	mkdir -p $(DESTDIR)/lib
+	install -m 0644 $^ $(DESTDIR)/lib
+
+uninstall:
+	rm -f $(DESTDIR)/lib/libpod-cpp.a
+	rm -f $(DESTDIR)/lib/libpod-cpp.so
+
+libpod-cpp.a: pod.cpp pod.hpp
+	$(CC) -o $@ -c $(CFLAGS) $<
+
+libpod-cpp.so: pod.cpp pod.hpp
+	$(CC) -o $@ $(SHAREDCFLAGS) $(CFLAGS) $<
+
+.PHONY: all clean

README

@@ -0,0 +1,113 @@
+                              POD Parser
+                                in C++
+
+This is a parser for Perl's POD markup language (see
+<https://perldoc.perl.org/perlpodspec.html>), entirely written in C++.
+
+This project is developed mainly for use for the generation of the
+scripting API docs of The Secret Chronicles of Dr. M. (TSC; see
+https://secretchronicles.org), but has been extracted into its own
+project as it turned out to be a little more than a simple parser for
+simple markup language. As a result of this history, the parser
+is written to be used in the context of HTML generation. If you need
+to generate something other than HTML, take a look at the ToHTML()
+methods of the various PodNode subclasses and implement similar
+ToYourOutput() methods yourself.
+
+                            - How to use -
+
+The C++ POD parser is written in C++11 and has no external
+dependencies. It is recommended to insert the two files directly into
+your project, but a simple Makefile is provided for building it as a
+library so it is possible to run:
+
+    $ make
+
+This is going to create a static and a shared library named
+libpod-cpp.a and libpod-cpp.so, respectively.
+
+After building the C++ POD parser, include the header:
+
+    #include "pod.hpp"
+
+Write a function that tells the parser how a file name looks like for
+any given class or module name:
+
+    std::string filename_cb(std::string classmodname)
+    {
+        return classmodname + ".html";
+    }
+
+Write another function that tells the parser how an HTML A tag's @name
+tag looks like if given a method name and the information about
+whether it's a class or module method:
+
+    std::string methodname_cb(bool cmethod, std::string methodname)
+    {
+        return cmethod ? methodname + "-cm" : methodname + "-im";
+    }
+
+Then, instanciate the parser with the string to parse and start
+the parsing process:
+
+    PodParser parser("=head1 The title\n\nLorem ipsum dolor sit amet\n",
+                     filename_cb, methodname_cb);
+    parser.parse();
+
+It is then possible to retrieve the list of parsed tokens (which are
+all subclasses of PodNode) and call the virtual PodNode::ToHTML()
+method on all of them in order to transform the tokens into HTML:
+
+    const std::vector<PodNode*> tokens = parser.GetTokens();
+    for(const PodNode* p_token: tokens) {
+        std::cout << p_token->ToHTML();
+    }
+
+If this is the entire processing required, a convenience function
+Pod::FormatHTML() exists that takes the token list as returned
+by PodParser::GetTokens() and does the exact same thing like
+the snippet above.
+
+    std::cout << Pod::FormatHTML(parser.GetTokens());
+
+Either way, this is going to dump the entire HTML for all the tokens
+to the standard output. Note there is no need to manually insert
+newlines between tokens. This is taken care of where necessary.
+
+                    - Limitations and Extensions -
+
+This parser is not entirely compliant with the POD specification. The
+most significant diversion is probably that it is not valid to use any
+kind of formatting code inside the link target of the L<> formatting
+code, especially not the E<> code.
+
+That being said, the parser is good enough to process TSC's scripting
+API documentation, which is its primary purpose. If not given too
+complicated markup, there should be no problem.
+
+TSC's scripting API is an object-oriented Ruby API. Therefore, the POD
+markup has been slightly extended to support typical Ruby API methods,
+which manifests itself in a modified behaviour of the L<> code. As
+with ordinary POD, an L<> formatting code without a bar (|) means an
+internal link to another object in the same documentation. Format
+L<Object/Section> can also be used as normal. However, additionally,
+it is possible to use an L<> code with one of the following two forms:
+
+1. L<Object#imethod> creates an internal link to the instance method
+   `imethod' of the class or module `Object'.
+2. L<Object::cmethod> creates an internal link to the class or module
+   method `cmethod' of the class or module `Object'.
+
+These two extensions can also be used with explicit link text, e.g.:
+
+    L<explicit link text|Object#imethod>
+
+Problems with obscure markup may be reported, but depending on the
+complexity of the problem might not be fixed if there is no chance
+that this markup occurs in TSC's scripting API documentation.
+
+                        - Legal Information -
+
+This parser has been written by Marvin Gülker, Unna (Germany, EU).
+It is licensed under the 2-clause BSD license. The exact license text
+can be found in the file LICENSE.