From b22fffce60bb66bee82a936121f455c47f3d45d4 Mon Sep 17 00:00:00 2001 From: lbonn Date: Mon, 4 Mar 2024 13:32:45 +0100 Subject: [PATCH] [Doc] Rewrite markdown for conversion to man * convert existing markup to use definition list (a bit hacky...) * rewrite title to pandoc man metadata * reduce heading nesting to match most man pages * inline code displayed as bold, also common man style --- doc/man_filter.lua | 225 ++++++++++++++++++ doc/meson.build | 5 +- doc/rofi-debugging.5.markdown | 2 +- doc/rofi-dmenu.5.markdown | 2 +- doc/rofi-keys.5.markdown | 318 +++++++++++++------------- doc/rofi-script.5.markdown | 2 +- doc/rofi-sensible-terminal.1.markdown | 2 +- doc/rofi-theme-selector.1.markdown | 2 +- doc/rofi-theme.5.markdown | 16 +- doc/rofi.1.markdown | 25 +- 10 files changed, 412 insertions(+), 187 deletions(-) create mode 100644 doc/man_filter.lua diff --git a/doc/man_filter.lua b/doc/man_filter.lua new file mode 100644 index 000000000..f1e5401a6 --- /dev/null +++ b/doc/man_filter.lua @@ -0,0 +1,225 @@ +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 outBlocks = {} + + 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(outBlocks, dl:walk()) + return {}, false + end + if idx >= d.start_idx and idx < d.end_idx then + -- drop + return {}, false + end + end + table.insert(outBlocks, el:walk()) + return nil, false + end, + } + + doc:walk(convert_defs) + + return pandoc.Pandoc(outBlocks, 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 + el:walk(f) + return {} -- drop + end + return nil + end, + } + + doc = doc:walk(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, + } + + return doc:walk(filter) +end + +local function code_in_strong(doc) + local filter = { + Code = function(el) + return pandoc.Strong(el.text) + end, + } + + return doc:walk(filter) +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) + local defs = find_defs(doc) + + doc = convert_defs(doc, defs) + + doc = extract_title(doc) + + doc = decrement_heading(doc) + + doc = code_in_strong(doc) + + return doc +end diff --git a/doc/meson.build b/doc/meson.build index c86dc7c00..3d6919aef 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -15,11 +15,12 @@ if pandoc.found() install_dest = join_paths(get_option('prefix'), get_option('mandir'), 'man' + section_number) man_targets += custom_target(f, - input: '.'.join([f, 'markdown']), + input: ['.'.join([f, 'markdown']), 'man_filter.lua'], output: f, command: [ 'pandoc', '--standalone', '--to=man', + '--lua-filter', '@INPUT1@', '-f', 'markdown-tex_math_dollars', - '@INPUT@', '-o', '@OUTPUT@' ], + '@INPUT0@', '-o', '@OUTPUT@' ], install: true, install_dir: install_dest, build_by_default: true, diff --git a/doc/rofi-debugging.5.markdown b/doc/rofi-debugging.5.markdown index 625e947d4..4df15d529 100644 --- a/doc/rofi-debugging.5.markdown +++ b/doc/rofi-debugging.5.markdown @@ -1,4 +1,4 @@ -% rofi-debugging(5) rofi | File Formats Manual +# rofi-debugging(5) ## NAME diff --git a/doc/rofi-dmenu.5.markdown b/doc/rofi-dmenu.5.markdown index a6626488a..27e484b3f 100644 --- a/doc/rofi-dmenu.5.markdown +++ b/doc/rofi-dmenu.5.markdown @@ -1,4 +1,4 @@ -% rofi-dmenu(5) rofi | File Formats Manual +# rofi-dmenu(5) ## NAME diff --git a/doc/rofi-keys.5.markdown b/doc/rofi-keys.5.markdown index c38643449..b6e264dfe 100644 --- a/doc/rofi-keys.5.markdown +++ b/doc/rofi-keys.5.markdown @@ -1,4 +1,4 @@ -% rofi-keys(5) rofi | File Formats Manual +# rofi-keys(5) ## NAME @@ -63,481 +63,481 @@ configuration { ## Keyboard Bindings -### **kb-primary-paste**: +`kb-primary-paste` Paste primary selection -**Default**: Control+V,Shift+Insert +Default: Control+V,Shift+Insert -### **kb-secondary-paste** +`kb-secondary-paste` Paste clipboard -**Default**: Control+v,Insert +Default: Control+v,Insert -### **kb-secondary-copy** +`kb-secondary-copy` Copy current selection to clipboard -**Default**: Control+c +Default: Control+c -### **kb-clear-line** +`kb-clear-line` Clear input line -**Default**: Control+w +Default: Control+w -### **kb-move-front** +`kb-move-front` Beginning of line -**Default**: Control+a +Default: Control+a -### **kb-move-end** +`kb-move-end` End of line -**Default**: Control+e +Default: Control+e -### **kb-move-word-back** +`kb-move-word-back` Move back one word -**Default**: Alt+b,Control+Left +Default: Alt+b,Control+Left -### **kb-move-word-forward** +`kb-move-word-forward` Move forward one word -**Default**: Alt+f,Control+Right +Default: Alt+f,Control+Right -### **kb-move-char-back** +`kb-move-char-back` Move back one char -**Default**: Left,Control+b +Default: Left,Control+b -### **kb-move-char-forward** +`kb-move-char-forward` Move forward one char -**Default**: Right,Control+f +Default: Right,Control+f -### **kb-remove-word-back** +`kb-remove-word-back` Delete previous word -**Default**: Control+Alt+h,Control+BackSpace +Default: Control+Alt+h,Control+BackSpace -### **kb-remove-word-forward** +`kb-remove-word-forward` Delete next word -**Default**: Control+Alt+d +Default: Control+Alt+d -### **kb-remove-char-forward** +`kb-remove-char-forward` Delete next char -**Default**: Delete,Control+d +Default: Delete,Control+d -### **kb-remove-char-back** +`kb-remove-char-back` Delete previous char -**Default**: BackSpace,Shift+BackSpace,Control+h +Default: BackSpace,Shift+BackSpace,Control+h -### **kb-remove-to-eol** +`kb-remove-to-eol` Delete till the end of line -**Default**: Control+k +Default: Control+k -### **kb-remove-to-sol** +`kb-remove-to-sol` Delete till the start of line -**Default**: Control+u +Default: Control+u -### **kb-accept-entry** +`kb-accept-entry` Accept entry -**Default**: Control+j,Control+m,Return,KP\_Enter +Default: Control+j,Control+m,Return,KP\_Enter -### **kb-accept-custom** +`kb-accept-custom` Use entered text as command (in ssh/run modes) -**Default**: Control+Return +Default: Control+Return -### **kb-accept-custom-alt** +`kb-accept-custom-alt` Use entered text as command (in ssh/run modes) -**Default**: Control+Shift+Return +Default: Control+Shift+Return -### **kb-accept-alt** +`kb-accept-alt` Use alternate accept command. -**Default**: Shift+Return +Default: Shift+Return -### **kb-delete-entry** +`kb-delete-entry` Delete entry from history -**Default**: Shift+Delete +Default: Shift+Delete -### **kb-mode-next** +`kb-mode-next` Switch to the next mode. -**Default**: Shift+Right,Control+Tab +Default: Shift+Right,Control+Tab -### **kb-mode-previous** +`kb-mode-previous` Switch to the previous mode. -**Default**: Shift+Left,Control+ISO\_Left\_Tab +Default: Shift+Left,Control+ISO\_Left\_Tab -### **kb-mode-complete** +`kb-mode-complete` Start completion for mode. -**Default**: Control+l +Default: Control+l -### **kb-row-left** +`kb-row-left` Go to the previous column -**Default**: Control+Page\_Up +Default: Control+Page\_Up -### **kb-row-right** +`kb-row-right` Go to the next column -**Default**: Control+Page\_Down +Default: Control+Page\_Down -### **kb-row-up** +`kb-row-up` Select previous entry -**Default**: Up,Control+p +Default: Up,Control+p -### **kb-row-down** +`kb-row-down` Select next entry -**Default**: Down,Control+n +Default: Down,Control+n -### **kb-row-tab** +`kb-row-tab` Go to next row, if one left, accept it, if no left next mode. -**Default**: +Default: -### **kb-element-next** +`kb-element-next` Go to next row. -**Default**: Tab +Default: Tab -### **kb-element-prev** +`kb-element-prev` Go to previous row. -**Default**: ISO\_Left\_Tab +Default: ISO\_Left\_Tab -### **kb-page-prev** +`kb-page-prev` Go to the previous page -**Default**: Page\_Up +Default: Page\_Up -### **kb-page-next** +`kb-page-next` Go to the next page -**Default**: Page\_Down +Default: Page\_Down -### **kb-row-first** +`kb-row-first` Go to the first entry -**Default**: Home,KP\_Home +Default: Home,KP\_Home -### **kb-row-last** +`kb-row-last` Go to the last entry -**Default**: End,KP\_End +Default: End,KP\_End -### **kb-row-select** +`kb-row-select` Set selected item as input text -**Default**: Control+space +Default: Control+space -### **kb-screenshot** +`kb-screenshot` Take a screenshot of the rofi window -**Default**: Alt+S +Default: Alt+S -### **kb-ellipsize** +`kb-ellipsize` Toggle between ellipsize modes for displayed data -**Default**: Alt+period +Default: Alt+period -### **kb-toggle-case-sensitivity** +`kb-toggle-case-sensitivity` Toggle case sensitivity -**Default**: grave,dead\_grave +Default: grave,dead\_grave -### **kb-toggle-sort** +`kb-toggle-sort` Toggle filtered menu sort -**Default**: Alt+grave +Default: Alt+grave -### **kb-cancel** +`kb-cancel` Quit rofi -**Default**: Escape,Control+g,Control+bracketleft +Default: Escape,Control+g,Control+bracketleft -### **kb-custom-1** +`kb-custom-1` Custom keybinding 1 -**Default**: Alt+1 +Default: Alt+1 -### **kb-custom-2** +`kb-custom-2` Custom keybinding 2 -**Default**: Alt+2 +Default: Alt+2 -### **kb-custom-3** +`kb-custom-3` Custom keybinding 3 -**Default**: Alt+3 +Default: Alt+3 -### **kb-custom-4** +`kb-custom-4` Custom keybinding 4 -**Default**: Alt+4 +Default: Alt+4 -### **kb-custom-5** +`kb-custom-5` Custom Keybinding 5 -**Default**: Alt+5 +Default: Alt+5 -### **kb-custom-6** +`kb-custom-6` Custom keybinding 6 -**Default**: Alt+6 +Default: Alt+6 -### **kb-custom-7** +`kb-custom-7` Custom Keybinding 7 -**Default**: Alt+7 +Default: Alt+7 -### **kb-custom-8** +`kb-custom-8` Custom keybinding 8 -**Default**: Alt+8 +Default: Alt+8 -### **kb-custom-9** +`kb-custom-9` Custom keybinding 9 -**Default**: Alt+9 +Default: Alt+9 -### **kb-custom-10** +`kb-custom-10` Custom keybinding 10 -**Default**: Alt+0 +Default: Alt+0 -### **kb-custom-11** +`kb-custom-11` Custom keybinding 11 -**Default**: Alt+exclam +Default: Alt+exclam -### **kb-custom-12** +`kb-custom-12` Custom keybinding 12 -**Default**: Alt+at +Default: Alt+at -### **kb-custom-13** +`kb-custom-13` Custom keybinding 13 -**Default**: Alt+numbersign +Default: Alt+numbersign -### **kb-custom-14** +`kb-custom-14` Custom keybinding 14 -**Default**: Alt+dollar +Default: Alt+dollar -### **kb-custom-15** +`kb-custom-15` Custom keybinding 15 -**Default**: Alt+percent +Default: Alt+percent -### **kb-custom-16** +`kb-custom-16` Custom keybinding 16 -**Default**: Alt+dead\_circumflex +Default: Alt+dead\_circumflex -### **kb-custom-17** +`kb-custom-17` Custom keybinding 17 -**Default**: Alt+ampersand +Default: Alt+ampersand -### **kb-custom-18** +`kb-custom-18` Custom keybinding 18 -**Default**: Alt+asterisk +Default: Alt+asterisk -### **kb-custom-19** +`kb-custom-19` Custom Keybinding 19 -**Default**: Alt+parenleft +Default: Alt+parenleft -### **kb-select-1** +`kb-select-1` Select row 1 -**Default**: Super+1 +Default: Super+1 -### **kb-select-2** +`kb-select-2` Select row 2 -**Default**: Super+2 +Default: Super+2 -### **kb-select-3** +`kb-select-3` Select row 3 -**Default**: Super+3 +Default: Super+3 -### **kb-select-4** +`kb-select-4` Select row 4 -**Default**: Super+4 +Default: Super+4 -### **kb-select-5** +`kb-select-5` Select row 5 -**Default**: Super+5 +Default: Super+5 -### **kb-select-6** +`kb-select-6` Select row 6 -**Default**: Super+6 +Default: Super+6 -### **kb-select-7** +`kb-select-7` Select row 7 -**Default**: Super+7 +Default: Super+7 -### **kb-select-8** +`kb-select-8` Select row 8 -**Default**: Super+8 +Default: Super+8 -### **kb-select-9** +`kb-select-9` Select row 9 -**Default**: Super+9 +Default: Super+9 -### **kb-select-10** +`kb-select-10` Select row 10 -**Default**: Super+0 +Default: Super+0 -### **kb-entry-history-up** +`kb-entry-history-up` Go up in the entry history. -**Default**: Control+Up +Default: Control+Up -### **kb-entry-history-down** +`kb-entry-history-down` Go down in the entry history. -**Default**: Control+Down +Default: Control+Down ## Mouse Bindings -### **ml-row-left** +`ml-row-left` Go to the previous column -**Default**: ScrollLeft +Default: ScrollLeft -### **ml-row-right** +`ml-row-right` Go to the next column -**Default**: ScrollRight +Default: ScrollRight -### **ml-row-up** +`ml-row-up` Select previous entry -**Default**: ScrollUp +Default: ScrollUp -### **ml-row-down** +`ml-row-down` Select next entry -**Default**: ScrollDown +Default: ScrollDown -### **me-select-entry** +`me-select-entry` Select hovered row -**Default**: MousePrimary +Default: MousePrimary -### **me-accept-entry** +`me-accept-entry` Accept hovered row -**Default**: MouseDPrimary +Default: MouseDPrimary -### **me-accept-custom** +`me-accept-custom` Accept hovered row with custom action -**Default**: Control+MouseDPrimary +Default: Control+MouseDPrimary ## SEE ALSO diff --git a/doc/rofi-script.5.markdown b/doc/rofi-script.5.markdown index 3df5f041b..53a463d2f 100644 --- a/doc/rofi-script.5.markdown +++ b/doc/rofi-script.5.markdown @@ -1,4 +1,4 @@ -% rofi-script(5) rofi | File Formats Manual +# rofi-script(5) ## NAME diff --git a/doc/rofi-sensible-terminal.1.markdown b/doc/rofi-sensible-terminal.1.markdown index 88323ab77..1406299dd 100644 --- a/doc/rofi-sensible-terminal.1.markdown +++ b/doc/rofi-sensible-terminal.1.markdown @@ -1,4 +1,4 @@ -% rofi-sensible-terminal(1) rofi | General Commands Manual +# rofi-sensible-terminal(1) ## NAME diff --git a/doc/rofi-theme-selector.1.markdown b/doc/rofi-theme-selector.1.markdown index 7e96189f0..1fa8b6fe7 100644 --- a/doc/rofi-theme-selector.1.markdown +++ b/doc/rofi-theme-selector.1.markdown @@ -1,4 +1,4 @@ -% rofi-theme-selector(1) rofi | General Commands Manual +# rofi-theme-selector(1) ## NAME diff --git a/doc/rofi-theme.5.markdown b/doc/rofi-theme.5.markdown index 31b86ba04..90a273f19 100644 --- a/doc/rofi-theme.5.markdown +++ b/doc/rofi-theme.5.markdown @@ -1,4 +1,4 @@ -% rofi-theme(5) rofi | File Formats Manual +# rofi-theme(5) ## NAME @@ -896,15 +896,19 @@ These are appended after the name or class of the widget. #### Example -`button selected.normal { }` +``` +button selected.normal { } -`element selected.urgent { }` +element selected.urgent { } +``` Currently only the entrybox and scrollbar have states: #### Entrybox -`{visible modifier}.{state}` +``` +{visible modifier}.{state} +``` Where `visible modifier` can be: - normal: no modification @@ -1551,7 +1555,9 @@ From the pango manpage: The string must have the form -`\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]`, +```text +\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS] +``` where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE\_OPTIONS is a whitespace-separated list of words where each diff --git a/doc/rofi.1.markdown b/doc/rofi.1.markdown index 9ec42b545..f2db1d653 100644 --- a/doc/rofi.1.markdown +++ b/doc/rofi.1.markdown @@ -1,4 +1,4 @@ -% rofi(1) rofi | General Commands Manual +# rofi(1) ## NAME @@ -312,7 +312,7 @@ launched. The time (in ms) boundary filter may take before switch from instant to delayed filter mode. - Default: 300 +Default: 300 A fallback icon can be specified for each mode: @@ -385,7 +385,7 @@ The format string for the `drun` dialog: Pango markup can be used to formatting the output. -Default: {name} [({generic})] +Default: `{name} [({generic})]` Note: Only fields enabled in `-drun-match-fields` can be used in the format string. @@ -419,8 +419,7 @@ Default: '-' ### Filtered menu sort -`-sort` to enable -`-no-sort` to disable +`-[no]-sort` Enable, disable sort for filtered menu. This setting can be changed at runtime (see `-kb-toggle-sort`). @@ -491,10 +490,7 @@ Default: *1* When one entry is left, automatically select it. -`-m` *num* -`-m` *name* -`-monitor` *num* -`-monitor` *name* +`-m` *num*, `-m` *name*, `-monitor` *num*, `-monitor` *name* Select monitor to display **rofi** on. It accepts as input: *primary* (if primary output is set), the *xrandr* output name, or integer number (in order @@ -588,8 +584,7 @@ Parse the `/etc/hosts` file for entries. Default: *disabled* -`-parse-known-hosts` -`-no-parse-known-hosts` +`-[no-]parse-known-hosts` Parse the `~/.ssh/known_hosts` file for entries. @@ -723,10 +718,9 @@ Note: This setting is ignored if `combi-hide-mode-prefix` is enabled. ### History -`-disable-history` -`-no-disable-history` (re-enable history) +`-[no-]disable-history` -Disable history +Disable or re-enable history `-max-history-size` *number* @@ -854,8 +848,7 @@ configuration { } ``` -`-click-to-exit` -`-no-click-to-exit` +`-[no-]click-to-exit` Click the mouse outside the **rofi** window to exit.