Skip to content

Commit 2896061

Browse files
ericonrflexibeast
ericonr
authored and
flexibeast
committed
void-docs.{in,1.in}: create script and man page.
This will be shipped in the void-docs package, and can be used to retrieve documentation pages. It is a template in order to support an arbitrary installation prefix. Move man page to section 1, since it is now primarily about the void-docs utility, but also contains info about the contents of the void-docs package. It is templated to allow PREFIX substituition. Use manually written man page instead of converted markdown. - credit to @flexibeast
1 parent c188ecb commit 2896061

File tree

7 files changed

+381
-83
lines changed

7 files changed

+381
-83
lines changed

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
book/
22
mandoc/
3-
void-docs.7
3+
void-docs
4+
void-docs.1

‎README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ the same protocol as the packages tree. For details, please read
88
## Building
99

1010
The [build.sh](./build.sh) script builds HTML, roff and PDF versions of the Void
11-
documentation and the `void-docs.7` man page. It requires the following Void
11+
documentation and the `void-docs.1` man page. It requires the following Void
1212
packages:
1313

1414
- `mdBook`
@@ -17,3 +17,7 @@ packages:
1717
- `texlive`
1818
- `perl`
1919
- `perl-JSON`
20+
21+
In order to build ans install everything, set the `PREFIX` and `DESTDIR`
22+
environment variables to appropriate values and run `build.sh` followed by
23+
`install.sh`.

‎build.sh

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
#!/bin/sh
2+
# uses PREFIX from environment
3+
: "${PREFIX:=/usr/local}"
24

5+
set -e
36
PATH="$PWD:$PATH"
47

58
# Build HTML mdbook
@@ -19,12 +22,12 @@ fd "\.md" ./ -x pandoc \
1922

2023
cd -
2124

22-
# Build reference man page
23-
echo "Building void-docs man page"
24-
pandoc \
25-
-V "title=void-docs" -V "section=7" -V "header=Void Docs" -s \
26-
-o "void-docs.7" "void-docs.md"
25+
# Build script
26+
echo "Building void-docs script and man page"
27+
sed -e "s,@PREFIX@,$PREFIX," void-docs.in > void-docs
28+
sed -e "s,@PREFIX@,$PREFIX," void-docs.1.in > void-docs.1
2729

2830
# Build PDF
31+
echo "Building PDF"
2932
pdflatex -output-directory=book/latex/ book/latex/handbook.tex >/dev/null
3033
pdflatex -output-directory=book/latex/ book/latex/handbook.tex >/dev/null

‎install.sh

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
#!/bin/sh
2+
# uses PREFIX and DESTDIR from environment
3+
: "${PREFIX:=/usr/local}"
24

3-
DESTDIR=$1
4-
DOC=$DESTDIR/usr/share/doc/void
5+
set -e
6+
7+
DOC=${DESTDIR}${PREFIX}/share/doc/void
58
mkdir -p $DOC/
69

710
cp -r src/ $DOC/markdown
8-
rm -r $DOC/markdown/theme
11+
rm -fr $DOC/markdown/theme
912

1013
cp -r book/html $DOC/html
1114

1215
cp -r mandoc/ $DOC/mandoc
1316

14-
mkdir -p $DESTDIR/usr/share/man/man7/
15-
install -m0644 void-docs.7 $DESTDIR/usr/share/man/man7/
17+
install -Dm0644 void-docs.1 ${DESTDIR}${PREFIX}/share/man/man1/
18+
install -Dm0755 void-docs ${DESTDIR}${PREFIX}/bin/

‎void-docs.1.in

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
.Dd August 2, 2020
2+
.Dt VOID-DOCS 1
3+
.Os
4+
.Sh NAME
5+
.Nm void-docs
6+
.Nd Access Void Linux documentation
7+
.Sh SYNOPSIS
8+
.Nm
9+
.Op OPTIONS
10+
.Op search terms
11+
.Sh DESCRIPTION
12+
The
13+
.Nm
14+
utility will attempt to launch different programs until it can find an
15+
adequate one to display the Void Linux documentation. If it is invoked
16+
without a search term, it will show the documentation's home
17+
page. Multiple search terms can be used to filter results. If the user
18+
has the
19+
.Xr fzf 1
20+
utility installed in their system, it will be used to browse the
21+
results. Otherwise,
22+
.Nm
23+
will display the first search result. If the
24+
.Fl s
25+
flag is used,
26+
.Nm
27+
will display the search results instead of the documentation.
28+
29+
The programs
30+
.Nm
31+
will try to use are, in order of preference:
32+
.Bl -dash
33+
.It
34+
For the HTML version:
35+
.Bl -dash
36+
.It
37+
the program specified in the environment variable
38+
.Ev BROWSER .
39+
.It
40+
.Xr xdg-open 1
41+
if either the
42+
.Ev DISPLAY
43+
or
44+
.Ev WAYLAND_DISPLAY
45+
environment variable is set.
46+
.It
47+
.Xr run-mailcap 1 .
48+
.It
49+
the TUI browsers
50+
.Xr lynx 1 ,
51+
.Xr w3m 1 ,
52+
and
53+
.Xr links 1 .
54+
.El
55+
.It
56+
For the Markdown version:
57+
.Bl -dash
58+
.It
59+
the Markdown processors
60+
.Sq mdcat
61+
and
62+
.Sq glow .
63+
.El
64+
.It
65+
For the roff (mdoc) version:
66+
.Bl -dash
67+
.It
68+
.Xr man 1 .
69+
.El
70+
.It
71+
For the PDF version:
72+
.Bl -dash
73+
.It
74+
.Xr xdg-open 1 ,
75+
and
76+
.Xr run-mailcap 1 .
77+
.It
78+
the PDF viewers
79+
.Xr zathura 1
80+
and
81+
.Xr okular 1 .
82+
.El
83+
.El
84+
.Pp
85+
It should be noted that for the PDF version,
86+
.Nm
87+
doesn't support search results.
88+
.Pp
89+
For a better browsing experience, installing
90+
.Xr fzf 1
91+
is recommended.
92+
.Sh OPTIONS
93+
.Bl -tag -width -x
94+
.It Fl h, Fl -help
95+
Show help message.
96+
.It Fl b
97+
Only try to display the HTML version.
98+
.It Fl m
99+
Only try to display the Markdown version.
100+
.It Fl r
101+
Only try to display the roff (mdoc) version.
102+
.It Fl p
103+
Open the PDF version.
104+
.It Fl s
105+
Only display search results.
106+
.El
107+
.Sh FILES
108+
The
109+
.Sq void-docs
110+
package contains a snapshot of the online documentation from
111+
.Lk https://docs.voidlinux.org ,
112+
which intends to document installation, configuration and system
113+
management for Void Linux. It is packaged in four formats.
114+
.Bl -tag -width x
115+
.It Pa @PREFIX@/share/doc/void/html
116+
Documentation in HTML format. Can be viewed with any browser, such as
117+
Mozilla Firefox or Chromium. Recommended when a GUI session is
118+
available, because it allows easy navigation between the documentation
119+
pages and has the same format as the official website. Can be accessed
120+
by pointing a browser to
121+
.Pa @PREFIX@/share/doc/void/html/index.html .
122+
.It Pa @PREFIX@/share/doc/void/markdown
123+
Documentation in Markdown format. Can be viewed as text files, using
124+
.Xr cat 1
125+
or
126+
.Xr less 1 ,
127+
or as formatted Markdown files, using applications such as
128+
.Sq mdcat
129+
or
130+
.Sq glow .
131+
The table of contents can be accessed via the
132+
.Pa @PREFIX@/share/doc/void/markdown/SUMMARY.md
133+
file.
134+
.It Pa @PREFIX@/share/doc/void/mandoc
135+
Documentation in roff (mdoc) format. Can be viewed using
136+
.Xr mandoc 1 .
137+
Using
138+
.Xr mandoc 1
139+
with the
140+
.Fl a
141+
option, which enables a pager, is recommended.
142+
.It Pa @PREFIX@/share/doc/void/handbook.pdf
143+
Documentation in PDF format. Can be viewed with any PDF viewer, such as
144+
.Xr zathura 1
145+
or
146+
.Xr okular 1 .
147+
.Sh EXAMPLES
148+
View the documentation page about the kernel:
149+
.Pp
150+
.Dl $ void-docs kernel
151+
.Pp
152+
View a documentation page inside another session:
153+
.Pp
154+
.Dl $ void-docs graphical-session kde
155+
.Pp
156+
View the homepage of the HTML documentation with
157+
.Xr qutebrowser 1 :
158+
.Pp
159+
.Dl $ qutebrowser @PREFIX@/share/doc/void/html/index.html
160+
.Pp
161+
View the summary of the Markdown documentation with
162+
.Xr less 1 :
163+
.Pp
164+
.Dl $ less @PREFIX@/share/doc/void/markdown/SUMMARY.md
165+
.Pp
166+
View the
167+
.Dq Kernel
168+
page of the Markdown documentation with
169+
.Sq mdcat :
170+
.Pp
171+
.Dl $ mdcat @PREFIX@/share/doc/void/markdown/config/kernel.md
172+
.Pp
173+
View the
174+
.Dq Cron
175+
page of the roff (mdoc) documentation with
176+
.Xr mandoc 1 :
177+
.Pp
178+
.Dl $ mandoc -a @PREFIX@/share/doc/void/mandoc/config/cron.7
179+
.Pp
180+
.Sh AVAILABILITY
181+
This man page is part of the void-docs package and is available from
182+
.Lk https://github.com/void-linux/void-docs .
183+
.Sh BUGS
184+
The Void Linux documentation tries to limit itself to content that is
185+
specific to Void. Therefore, if you feel something is missing, it
186+
might have been deliberate. However, if there is any information that
187+
is mistaken, outdated or indeed missing, please report an issue at
188+
.Lk https://github.com/void-linux/void-docs .

0 commit comments

Comments
 (0)