On Sat 29/04/2023 08:21, Mikolaj Kucharski wrote: > Hi, > > I just wanted to have a quick look at `man borg` and it doesn't look > right. > > Do you guys see the same?
Yes, think so. Manual page is displayed with markup language. I'm not familiar with the language and not sure if the attached patch is the right solution. At least with this patch 'man borg' looks good. Hopefully someone - with more knowledge on manpages - chimes in. diff --git Makefile Makefile index 2bf9cd961fa..3ce565536c1 100644 --- Makefile +++ Makefile @@ -1,7 +1,7 @@ PORTROACH = limit:^1\.1\. MODPY_EGG_VERSION = 1.1.18 -REVISION = 3 +REVISION = 4 WANTLIB = ${COMPILER_LIBCXX} b2 crypto m diff --git patches/patch-docs_man_borg_1 patches/patch-docs_man_borg_1 new file mode 100644 index 00000000000..2bfdc8ebd57 --- /dev/null +++ patches/patch-docs_man_borg_1 @@ -0,0 +1,157 @@ +Index: docs/man/borg.1 +--- docs/man/borg.1.orig ++++ docs/man/borg.1 +@@ -27,29 +27,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-lev + .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] + .in \\n[rst2man-indent\\n[rst2man-indent-level]]u + .. +-.TH "" "" "" "" ++.TH "BORG" 1 "2023-03-22" "" "borg backup tool" + .SH NAME +- \- +-.SH BORG +-.SS deduplicating and encrypting backup tool +-.INDENT 0.0 +-.TP +-.B Author +-The Borg Collective +-.TP +-.B Date +-2017\-02\-05 +-.TP +-.B Manual section +-1 +-.TP +-.B Manual group +-borg backup tool +-.UNINDENT +-.SS SYNOPSIS ++borg \- deduplicating and encrypting backup tool ++.SH SYNOPSIS + .sp + borg [common options] <command> [options] [arguments] +-.SS DESCRIPTION ++.SH DESCRIPTION + .\" we don't include the README.rst here since we want to keep this terse. + . + .sp +@@ -66,8 +50,8 @@ Borg stores a set of files in an \fIarchive\fP\&. A \f + of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not + distinguish archives from each other in any way other than their name, + it does not matter when or where archives were created (e.g. different hosts). +-.SS EXAMPLES +-.SS A step\-by\-step example ++.SH EXAMPLES ++.SH A step\-by\-step example + .INDENT 0.0 + .IP 1. 3 + Before a backup can be made a repository has to be initialized: +@@ -201,8 +185,8 @@ reports during command execution. You can also add th + get other informational messages. + .UNINDENT + .UNINDENT +-.SS NOTES +-.SS Positional Arguments and Options: Order matters ++.SH NOTES ++.SH Positional Arguments and Options: Order matters + .sp + Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example) + to the left or right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP +@@ -222,7 +206,7 @@ borg create repo::archive \-s \-\-progress path # BAD + .UNINDENT + .sp + This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP +-.SS Repository URLs ++.SH Repository URLs + .sp + \fBLocal filesystem\fP (or locally mounted network filesystem): + .sp +@@ -278,7 +262,7 @@ to use the default \- it will be read from BORG_REPO t + .sp + Use \fB::\fP syntax to give the repo URL when syntax requires giving a positional + argument for the repo (e.g. \fBborg mount :: /mnt\fP). +-.SS Repository / Archive Locations ++.SH Repository / Archive Locations + .sp + Many commands want either a repository (just give the repo URL, see above) or + an archive location, which is a repo URL followed by \fB::archive_name\fP\&. +@@ -290,7 +274,7 @@ name). + .sp + If you have set BORG_REPO (see above) and an archive location is needed, use + \fB::archive_name\fP \- the repo URL part is then read from BORG_REPO. +-.SS Logging ++.SH Logging + .sp + Borg writes all log output to stderr by default. But please note that something + showing up on stderr does \fInot\fP indicate an error condition just because it is +@@ -343,7 +327,7 @@ Options \fB\-\-critical\fP and \fB\-\-error\fP are pro + their usage is not recommended as you might miss important information. + .UNINDENT + .UNINDENT +-.SS Return codes ++.SH Return codes + .sp + Borg can exit with the following return codes (rc): + .TS +@@ -386,7 +370,7 @@ _ + .sp + If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated + level as the last log entry. +-.SS Environment Variables ++.SH Environment Variables + .sp + Borg uses some environment variables for automation: + .INDENT 0.0 +@@ -597,7 +581,7 @@ Be very careful when using the "yes" sayers, the warni + Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g. + mode 600, root:root). + .UNINDENT +-.SS File systems ++.SH File systems + .sp + We strongly recommend against using Borg (or any other database\-like + software) on non\-journaling file systems like FAT, since it is not +@@ -630,14 +614,14 @@ Hardlinks are needed for \fIborg_upgrade\fP (if \fB\-\ + Also hardlinks are used for more safe and secure file updating (e.g. of the repo + config file), but the code tries to work also if hardlinks are not supported. + .UNINDENT +-.SS Units ++.SH Units + .sp + To display quantities, Borg takes care of respecting the + usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so + \fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are + indicated using the \fI\%IEC binary prefixes\fP, + using powers of two (so \fBKiB\fP means 1024 bytes). +-.SS Date and Time ++.SH Date and Time + .sp + We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and + HH:MM:SS (24h clock). +@@ -646,7 +630,7 @@ For more information about that, see: \fI\%https://xkc + .sp + Unless otherwise noted, we display local date and time. + Internally, we store and process date and time as UTC. +-.SS Resource Usage ++.SH Resource Usage + .sp + Borg might use a lot of resources depending on the size of the data set it is dealing with. + .sp +@@ -750,7 +734,7 @@ operations used for transaction support also go over t + you backup multiple sources to one target repository, additional traffic + happens for cache resynchronization. + .UNINDENT +-.SS Support for file metadata ++.SH Support for file metadata + .sp + Besides regular file and directory structures, Borg can preserve + .INDENT 0.0 +@@ -899,7 +883,7 @@ This includes resource forks on Mac OS X. + .IP [7] 5 + aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms. + The BSDs define additional flags. +-.SS SEE ALSO ++.SH SEE ALSO + .sp + \fIborg\-common(1)\fP for common command line options + .sp