Browse Source

Use scdoc to generate manpages

Aqua-sama 4 weeks ago
parent
commit
72575ccadb
Signed by: Aqua-sama <aqua@iserlohn-fortress.net> GPG Key ID: 5378B8349C1D5ADA
6 changed files with 125 additions and 92 deletions
  1. 2
    4
      .gitignore
  2. 88
    0
      doc/man/smolbote.1.scd
  3. 11
    14
      doc/man/smolbote.5.scd
  4. 22
    34
      doc/meson.build
  5. 0
    39
      doc/smolbote.7.asciidoc
  6. 2
    1
      linux/makepkg/PKGBUILD

+ 2
- 4
.gitignore View File

@@ -12,9 +12,7 @@ test/plugins.d
12 12
 .config
13 13
 .config.old
14 14
 
15
-smolbote.*
16
-
17 15
 # manpages
18
-doc/smolbote.5
19
-doc/smolbote.7
16
+smolbote.1
17
+smolbote.5
20 18
 

+ 88
- 0
doc/man/smolbote.1.scd View File

@@ -0,0 +1,88 @@
1
+smolbote(1)
2
+
3
+# NAME
4
+
5
+smolbote - yet another no-frills web browser
6
+
7
+# SYNOPSIS
8
+
9
+*poi* [options] [command/URL(s)]
10
+
11
+# DESCRIPTION
12
+
13
+smolbote is a cross-platform keep-it-simple free software web browser that
14
+uses Qt and QtWebEngine.
15
+
16
+# USAGE
17
+
18
+## Command-line options
19
+- `-h`, `--help`: Display command-line options list.
20
+- `-v`, `--version`: Display version information.
21
+- `--build`: Display build commit.
22
+- `-c`, `--config`: Set configuration file.
23
+- `--no-remote`: Don't check for other instances when starting.
24
+- `-s, --session`: Open the selected session.
25
+- `--pick-session`: Open all available sessions and select which one to open.
26
+
27
+## Profiles
28
+A Profile is a collection of settings, policies, scripts, cookies, cache and
29
+history. Profiles can be used to isolate pages from each other.
30
+
31
+Off-the-record profiles only use in-memory cache and save no files to disk.
32
+
33
+Profiles can be either temporary or permanent. Temporary profiles expire when
34
+the application is closed, whereas permanent profiles are kept between runs.
35
+
36
+Each window has a default profile it uses when opening new tabs. This can be
37
+changed from the window's menu. Additionally, tabs can have their profiles
38
+individually changed from their context menu.
39
+
40
+Because profiles store all their data separately, you can log in into the same
41
+site with a different account from each profile. However, links opened into new
42
+tabs will still use the subwindow's default profile. For example, you can set a
43
+profile to hold login information for a site, but all new tabs opened from that
44
+site would still be using the default off-the-record profile.
45
+
46
+## Plugins
47
+Plugins a way of extending smolbote's functionality using the Qt plugin system.
48
+They are not to be confused with NPAPI/PPAPI or WebExtension plugins.
49
+
50
+To enable a plugin either copy it or symlink it in the plugins.path location,
51
+or set its absolute path as the plugins.path.
52
+
53
+## Filters
54
+smolbote has a singular URL request filter that is installed onto all profiles.
55
+Any setting applied to it will be applied to all profiles.
56
+
57
+filter.header: A list of header-value pairs, separated by a colon (':').
58
+
59
+You can specify multiple headers by using --filter.header multiple times:
60
+```
61
+poi --filter.header "Dnt:1" --filter.header "Accept:text/html"
62
+```
63
+
64
+# SEE ALSO
65
+
66
+*smolbote*(5) - configuration file and options
67
+
68
+# AUTHORS
69
+
70
+Maintained by <aqua@iserlohn-fortress.net>.
71
+
72
+Up-to-date sources can be found at https://neueland.iserlohn-fortress.net/gitea/aqua/smolbote
73
+
74
+Bug reports and patches can be submitted by email to <aqua@iserlohn-fortress.net>.
75
+
76
+# COPYRIGHT
77
+
78
+This program is free software: you can redistribute it and/or modify
79
+it under the terms of the GNU General Public License version 3 as
80
+published by the Free Software Foundation.
81
+
82
+This program is distributed in the hope that it will be useful,
83
+but WITHOUT ANY WARRANTY; without even the implied warranty of
84
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
85
+GNU General Public License for more details.
86
+
87
+You should have received a copy of the GNU General Public License
88
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

doc/smolbote.5.asciidoc → doc/man/smolbote.5.scd View File

@@ -1,14 +1,11 @@
1
-= smolbote(5)
2
-:doctype: manpage
3
-:man source: smolbote configuration
4
-:man manual: smolbote configuration manpage
5
-:toc:
6
-:homepage: https://neueland.iserlohn-fortress.net/smolbote/
7
-
8
-== Name
1
+smolbote(5) "smolbote configuration"
2
+
3
+# NAME
4
+
9 5
 smolbote - configuration file and options description
10 6
 
11
-== Description
7
+# DESCRIPTION
8
+
12 9
 The smolbote configuration is loaded at startup, and is not reloaded when
13 10
 changed. By default (without any plugins), the browser does not change its
14 11
 configuration or overwrite this file. Thus, it can be made read-only.
@@ -20,9 +17,9 @@ Lines starting with *#* are considered comments and ignored.
20 17
 Options taking multiple values (list options) can have multiple values set by
21 18
 using the same option name multiple times.
22 19
 
23
-== Sections
20
+# SECTIONS
24 21
 
25
-=== Browser Options
22
+## Browser Options
26 23
 
27 24
 *browser.stylesheet* (arg):: TODO
28 25
 
@@ -53,7 +50,7 @@ Default downloads location.
53 50
 *downloads.shortcut* (arg=Ctrl+D)::
54 51
 Show/Hide downloads widget shortcut.
55 52
 
56
-=== UI Options
53
+## UI Options
57 54
 
58 55
 *mainwindow.height* (arg=720)
59 56
 *mainwindow.width* (arg=1280)
@@ -93,8 +90,8 @@ Show/Hide downloads widget shortcut.
93 90
 *subwindow.shortcuts.moveRight* (arg=Ctrl+Shift+P):: Move tab to the right
94 91
 *subwindow.shortcuts.fullscreen* (arg=F11):: Show page fullscreen
95 92
 
96
-=== Security Options
97
-  
93
+## Security Options
94
+
98 95
 *filter.hosts* (arg=~/.config/smolbote/hosts.d):: Hostlist
99 96
 *filter.adblock* arg:: TODO
100 97
 *filter.header* (list)::

+ 22
- 34
doc/meson.build View File

@@ -1,42 +1,30 @@
1
-asciidoctor = find_program('asciidoctor', required: get_option('manpage'), disabler: true)
1
+scdoc = find_program('scdoc', required: get_option('manpage'), disabler: true)
2
+sh = find_program('sh', required: get_option('manpage'), native: true, disabler: true)
2 3
 
3
-custom_target('manpage.7',
4
-    # list depend_files so the output can be updated if any of them are changed
5
-    depend_files: ['smolbote.7.asciidoc', 'Usage/CommandLine.asciidoc', 'Usage/Configuration.asciidoc', 'Usage/Profile.asciidoc', 'Usage/Plugins.asciidoc', 'Usage/Filter.asciidoc'],
6
-    
7
-    input: 'smolbote.7.asciidoc',
8
-    output: 'smolbote.7',
4
+man_files = ['man/smolbote.1.scd', 'man/smolbote.5.scd']
9 5
 
10
-    command: [asciidoctor, '--backend=manpage', '--out-file=@OUTPUT@', '@INPUT@'],
6
+foreach input : man_files
7
+  topic = input.split('/')[-1].split('.')[-3]
8
+  section = input.split('.')[-2]
9
+  output = '@0@.@1@'.format(topic, section)
11 10
 
12
-    build_by_default: get_option('manpage').enabled(),
13
-    install: get_option('manpage').enabled(),
14
-    install_dir: join_paths(get_option('mandir'), 'man7')
15
-)
11
+  message('creating manpage target ' + output)
12
+  custom_target(output,
13
+    build_by_default: true,
16 14
 
17
-custom_target('manpage.5',
18
-    # list of files this target depends on
19
-    depend_files: ['smolbote.5.asciidoc'],
15
+    input: input,
16
+    output: output,
20 17
 
21
-    input: 'smolbote.5.asciidoc',
22
-    output: 'smolbote.5',
18
+    # scdoc takes input from stdin, and prints its output to stdout
19
+    # meson uses 'capture' to store stdout to output, but there is no stdin toggle
20
+    #command: [scdoc],
21
+    #capture: true,
23 22
 
24
-    command: [asciidoctor, '--backend=manpage', '--out-file=@OUTPUT@', '@INPUT@'],
23
+    # workaround using sh
24
+    command: [sh, '-c', '@0@ < @INPUT0@ > @OUTPUT0@'.format(scdoc.path())],
25 25
 
26
-    build_by_default: get_option('manpage').enabled(),
27
-    install: get_option('manpage').enabled(),
28
-    install_dir: get_option('mandir') / 'man5'
29
-)
30
-
31
-custom_target('manual',
32
-    depend_files: ['smolbote.asciidoc'],
33
-
34
-    input: 'smolbote.asciidoc',
35
-    output: 'manual.html',
36
-
37
-    command: [asciidoctor, '-a', 'imagesdir=images', '--out-file=@OUTPUT@', '@INPUT@'],
38
-
39
-    build_by_default: false,
40
-    install: false
41
-)
26
+    install: true,
27
+    install_dir: '@0@/man@1@'.format(get_option('mandir'), section)
28
+  )
29
+endforeach
42 30
 

+ 0
- 39
doc/smolbote.7.asciidoc View File

@@ -1,39 +0,0 @@
1
-= smolbote(7)
2
-:doctype: manpage
3
-:man source: smolbote
4
-:man manual: smolbote manpage
5
-:toc:
6
-:homepage: https://neueland.iserlohn-fortress.net/smolbote/
7
-
8
-== Name
9
-smolbote - yet another no-frills web browser
10
-
11
-== Synopsis
12
-*poi* ['-OPTION' ['...']] ['COMMAND'] ['URL' ['...']]
13
-
14
-== Description
15
-smolbote is a cross-platform keep-it-simple free software web browser based on
16
-Qt and QtWebEngine.
17
-
18
-include::Usage/CommandLine.asciidoc[]
19
-
20
-include::Usage/Configuration.asciidoc[]
21
-
22
-include::Usage/Profile.asciidoc[]
23
-
24
-include::Usage/Plugins.asciidoc[]
25
-
26
-include::Usage/Filter.asciidoc[]
27
-
28
-== Copyright
29
-This program is free software: you can redistribute it and/or modify
30
-it under the terms of the GNU General Public License version 3 as
31
-published by the Free Software Foundation.
32
-
33
-This program is distributed in the hope that it will be useful,
34
-but WITHOUT ANY WARRANTY; without even the implied warranty of
35
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
36
-GNU General Public License for more details.
37
-
38
-You should have received a copy of the GNU General Public License
39
-along with this program.  If not, see <http://www.gnu.org/licenses/>.

+ 2
- 1
linux/makepkg/PKGBUILD View File

@@ -14,7 +14,7 @@ license=('GPL3')
14 14
 
15 15
 depends=('qt5-webengine>=5.11.0' 'boost-libs>=1.66.0')
16 16
 optdepends=('firejail: launch a sandboxed instance')
17
-makedepends=('git' 'meson' 'boost' 'python-kconfiglib' 'openssl')
17
+makedepends=('git' 'meson' 'boost' 'python-kconfiglib' 'openssl' 'scdoc')
18 18
 
19 19
 # this is the central repository
20 20
 source=("git+https://neueland.iserlohn-fortress.net/gitea/aeon/smolbote.git"
@@ -85,6 +85,7 @@ build() {
85 85
     # b_lto: Use link time optimization
86 86
     meson --buildtype=plain --prefix=/usr/local --auto-features=disabled \
87 87
         -Db_pie=true -Db_lto=true -Dcpp_link_args="-fuse-ld=gold" \
88
+        -Dmanpage=enabled \
88 89
         $srcdir/build
89 90
 
90 91
     # Run menuconfig

Loading…
Cancel
Save