|
| 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