[Doc] Switch to pandoc and remove generated files

.github/actions/setup/action.yml

@@ -34,6 +34,7 @@ runs:
           libxkbcommon-dev \
           libxkbcommon-x11-dev \
           ninja-build \
+          pandoc \
           python3-pip \
           python3-setuptools \
           python3-wheel \

Makefile.am

@@ -172,19 +172,52 @@ rofi_LDADD=\
 	$(LIBS)
 
 ##
-# Manpage
+# Manpages
 ##
+
+.PHONY: generate-manpage
+
+if FOUND_PANDOC
+
+generate-manpage: doc/rofi.1\
+	doc/rofi-sensible-terminal.1\
+	doc/rofi-theme-selector.1\
+	doc/rofi-debugging.5\
+	doc/rofi-dmenu.5\
+	doc/rofi-keys.5\
+	doc/rofi-script.5\
+	doc/rofi-theme.5
+
+doc/rofi.1: doc/rofi.1.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-sensible-terminal.1: doc/rofi-sensible-terminal.1.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-theme-selector.1: doc/rofi-theme-selector.1.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-debugging.5: doc/rofi-debugging.5.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-dmenu.5: doc/rofi-dmenu.5.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-keys.5: doc/rofi-keys.5.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-script.5: doc/rofi-script.5.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+doc/rofi-theme.5: doc/rofi-theme.5.markdown
+	pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$<
+
+endif
+
 dist_man1_MANS=\
 	doc/rofi.1\
-	doc/rofi-theme-selector.1\
-	doc/rofi-sensible-terminal.1
+	doc/rofi-sensible-terminal.1\
+	doc/rofi-theme-selector.1
 
 dist_man5_MANS=\
-	doc/rofi-theme.5\
 	doc/rofi-debugging.5\
-	doc/rofi-keys.5\
 	doc/rofi-dmenu.5\
-	doc/rofi-script.5
+	doc/rofi-keys.5\
+	doc/rofi-script.5\
+	doc/rofi-theme.5
 
 EXTRA_DIST += \
 	doc/rofi-theme.5.markdown \
@@ -254,19 +287,7 @@ EXTRA_DIST+=\
 	doc/default_configuration.rasi\
 	doc/default_theme.rasi\
 	Changelog
-##
-# Indent
-##
 
-update-manpage: $(top_srcdir)/doc/rofi-theme-selector.1.markdown $(top_srcdir)/doc/rofi.1.markdown $(top_srcdir)/doc/rofi-theme.5.markdown $(top_srcdir)/doc/rofi-script.5.markdown ${top_srcdir}/doc/rofi-sensible-terminal.1.markdown ${top_srcdir}/doc/rofi-keys.5.markdown ${top_srcdir}/doc/rofi-dmenu.5.markdown $(top_srcdir)/doc/rofi-debugging.5.markdown
-	go-md2man -in $(top_srcdir)/doc/rofi.1.markdown -out $(top_srcdir)/doc/rofi.1
-	go-md2man -in $(top_srcdir)/doc/rofi-theme-selector.1.markdown -out $(top_srcdir)/doc/rofi-theme-selector.1
-	go-md2man -in $(top_srcdir)/doc/rofi-theme.5.markdown -out $(top_srcdir)/doc/rofi-theme.5
-	go-md2man -in $(top_srcdir)/doc/rofi-debugging.5.markdown -out $(top_srcdir)/doc/rofi-debugging.5
-	go-md2man -in $(top_srcdir)/doc/rofi-keys.5.markdown -out $(top_srcdir)/doc/rofi-keys.5
-	go-md2man -in $(top_srcdir)/doc/rofi-script.5.markdown -out $(top_srcdir)/doc/rofi-script.5
-	go-md2man -in $(top_srcdir)/doc/rofi-dmenu.5.markdown -out $(top_srcdir)/doc/rofi-dmenu.5
-	go-md2man -in $(top_srcdir)/doc/rofi-sensible-terminal.1.markdown -out $(top_srcdir)/doc/rofi-sensible-terminal.1
 
 ##
 # Rofi test program
@@ -656,6 +677,8 @@ EXTRA_DIST += \
 	subprojects/libgwater/wayland-server/meson.build \
 	subprojects/libgwater/meson.build \
 	subprojects/libgwater/win/meson.build \
+	subprojects/libnkutils/bindings/meson.build \
+	subprojects/libnkutils/core/meson.build \
 	subprojects/libnkutils/meson.build \
 	subprojects/libnkutils/meson_options.txt \
 	subprojects/libgwater/wayland/libgwater-wayland.h \

configure.ac

@@ -169,6 +169,13 @@ AC_ARG_ENABLE([check], AS_HELP_STRING([--disable-check], [Build with checks usin
 AS_IF([test "x${enable_check}" != "xno"], [ PKG_CHECK_MODULES([check],[check >= 0.11.0], [HAVE_CHECK=1]) ])
 AM_CONDITIONAL([USE_CHECK],  [test "x${enable_check}" != "xno" && test "$HAVE_CHECK" -eq 1])
 
+dnl ---------------------------------------------------------------------
+dnl Build man pages
+dnl ---------------------------------------------------------------------
+AC_ARG_ENABLE([man], AS_HELP_STRING([--disable-man], [Build man pages (default: enabled)]))
+
+AS_IF([test "x$enable_man" != "xno" ], [ AC_CHECK_PROG([pandoc], pandoc, [yes])])
+AM_CONDITIONAL([FOUND_PANDOC], [test "x$pandoc" = xyes])
 
 dnl ---------------------------------------------------------------------
 dnl Gets the resource compile tool path.
@@ -210,6 +217,11 @@ echo "Check based tests            Enabled"
 else
 echo "Check based tests            Disabled"
 fi
+if test "x${enable_man}" != "xno" && test "x$pandoc" = "xyes"; then
+echo "Build man pages              Enabled"
+else
+echo "Build man pages              Disabled"
+fi
 echo "-------------------------------------"
 echo "Now type 'make' to build"
 echo ""

doc/README.md

@@ -1,7 +1,7 @@
-Manpages are build using [go-md2man](https://github.com/cpuguy83/go-md2man)
+Manpages are build using [pandoc](https://pandoc.org/)
 
 Manpages can be updated using the following make command:
 
 ```
-make update-manpage
+make generate-manpage
 ```

doc/man_filter.lua

@@ -0,0 +1,237 @@
+local Def = {}
+
+function Def:new(d)
+    -- init with empty def
+    if d == nil then
+        d = {
+            start_idx = nil,
+            end_idx = nil,
+            def_par = nil,
+            content = {},
+        }
+    end
+    setmetatable(d, self)
+    self.__index = self
+    return d
+end
+
+function Def:init(start_idx, el)
+    self.start_idx = start_idx
+    self.def_par = el
+end
+
+function Def:append(el)
+    if self.start_idx ~= nil then
+        table.insert(self.content, el)
+    end
+end
+
+function Def:stop(end_idx)
+    if self.start_idx == nil then
+        return nil
+    end
+    local out = self:new({
+        start_idx = self.start_idx,
+        end_idx = end_idx,
+        def_par = self.def_par,
+        content = self.content,
+    })
+    self.start_idx = nil
+    self.end_idx = nil
+    self.def_par = nil
+    self.content = {}
+    return out
+end
+
+function Def:to_string()
+    return string.format("start: %d, end: %d, def_par: %s", self.start_idx, self.end_idx, self.def_par)
+end
+
+function find_defs(doc)
+    local defs = {}
+    local idx = 0
+    local def = Def:new()
+
+    -- find defintions:
+    -- * start at paragraphs with `word` ...
+    -- * stop at next definition or next header
+    local filter = {
+        traverse = "topdown",
+        Para = function(el)
+            idx = idx + 1
+
+            local new_def_start = #el.content >= 1 and el.content[1].tag == "Code"
+
+            if new_def_start then
+                local newd = def:stop(idx - 1)
+                table.insert(defs, newd)
+
+                def:init(idx, el.content)
+            else
+                def:append(el)
+            end
+            return nil, false
+        end,
+        Block = function(el)
+            idx = idx + 1
+            def:append(el)
+            -- stop exploring after one nesting level
+            return nil, false
+        end,
+        Header = function(el)
+            idx = idx + 1
+            local newd = def:stop(idx - 1)
+            table.insert(defs, newd)
+            return nil, false
+        end,
+    }
+
+    doc:walk(filter)
+    local newd = def:stop(idx - 1)
+    table.insert(defs, newd)
+
+    return defs
+end
+
+function convert_defs(doc, defs)
+    local idx = 0
+    local out_blocks = {}
+
+    local convert_defs = {
+        traverse = "topdown",
+        Block = function(el)
+            idx = idx + 1
+            for _, d in ipairs(defs) do
+                if idx == d.end_idx then
+                    local dl = pandoc.DefinitionList({ { d.def_par, { d.content } } })
+                    table.insert(out_blocks, dl:walk())
+                    return {}, false
+                end
+                if idx >= d.start_idx and idx < d.end_idx then
+                    -- drop
+                    return {}, false
+                end
+            end
+            table.insert(out_blocks, el:walk())
+            return nil, false
+        end,
+    }
+
+    doc:walk(convert_defs)
+
+    return pandoc.Pandoc(out_blocks, doc.meta)
+end
+
+-- for <2.17 compatibility
+-- equivalent to `doc:walk(filter)`
+local function walk_doc(doc, filter)
+    local div = pandoc.Div(doc.blocks)
+    local blocks = pandoc.walk_block(div, filter).content
+    return pandoc.Pandoc(blocks, doc.meta)
+end
+
+local function extract_title(doc)
+    local title = {}
+    local section
+    local filter = {
+        Header = function(el)
+            local f = {
+                Str = function(el)
+                    if el.text:find("%(1%)") ~= nil then
+                        section = "General Commands Manual"
+                    elseif el.text:find("%(5%)") ~= nil then
+                        section = "File Formats Manual"
+                    end
+                    table.insert(title, el)
+                end,
+                Inline = function(el)
+                    table.insert(title, el)
+                end,
+            }
+            if el.level == 1 then
+                pandoc.walk_block(el, f)
+                return {} -- drop
+            end
+            return nil
+        end,
+    }
+
+    doc = walk_doc(doc, filter)
+
+    local to_inline = function(s)
+        local r = {}
+        for w in s:gmatch("%S+") do
+            table.insert(r, pandoc.Str(w))
+            table.insert(r, pandoc.Space())
+        end
+        table.remove(r, #r)
+        return r
+    end
+
+    if section ~= nil then
+        for _, e in ipairs({
+            pandoc.Space(),
+            pandoc.Str("rofi"),
+            pandoc.Space(),
+            pandoc.Str("|"),
+            table.unpack(to_inline(section)),
+        }) do
+            table.insert(title, e)
+        end
+    end
+
+    doc.meta = pandoc.Meta({
+        title = pandoc.MetaInlines(title),
+    })
+
+    return doc
+end
+
+local function decrement_heading(doc)
+    local filter = {
+        Header = function(el)
+            if el.level > 1 then
+                el.level = el.level - 1
+                return el
+            end
+            return nil
+        end,
+    }
+
+    doc = walk_doc(doc, filter)
+    return doc
+end
+
+local function code_in_strong(doc)
+    local filter = {
+        Code = function(el)
+            return pandoc.Strong(el.text)
+        end,
+    }
+
+    doc = walk_doc(doc, filter)
+    return doc
+end
+
+--- Run filtering function through whole document
+--
+--  * find argument definitions: paragraph starting with inline code (`-arg`)
+--  * replace the paragraphs until the end of the definition with a DefinitionList
+--  * extract metadata title from main heading
+--  * decrement heading from 1 for better display
+--  * convert inline code text to Strong as usual in man pages
+function Pandoc(doc)
+    if PANDOC_VERSION >= pandoc.types.Version("2.17.0") then
+        -- 2.17 is required for topdown traversal
+        local defs = find_defs(doc)
+        doc = convert_defs(doc, defs)
+    end
+
+    doc = extract_title(doc)
+
+    doc = decrement_heading(doc)
+
+    doc = code_in_strong(doc)
+
+    return doc
+end