This patch add stubs of documentation for ansicat(1), netcache(1),
migrate-offpunk-cache(1) and opnk(1) in prevision of offpunk 2.0
release. The migration script manual notably resolves issue #15.
That’s awesome! Thanks a lot for providing that.
What’s the easiest way to maintain such a man page? Is there a way to
generate them or is it easier to simply learn the format and manually
update the pages?
We have had this discussion a few months ago in the packagers
mailing list, so I unravelled it as I recalled there were
interesting propositions to help with manual pages
maintenance[1]. Don't worry, it's okay to change your mind. ;)
Given the comment from Klaus, I guess you might be interested to
investigate the use of argparse-manpage[2] for producing the
manuals automatically out of the help fields that are defined in
the program. That would allow you to deduplicate the content of
the manuals and the help fields of the scripts. It didn't look
completely obvious to put into place to me, but once it's there,
the documentation is not a maintenance burden anymore.
Yep, this really looks the way to go for me. I believe that man pages
should be generated either by a script or within the build with
argparse-manpage.
But, indeed, it is not obvious. I can’t make it works as it doesn’t want
to import other files in the folder.
If anybody is familiar with argparse, this would be a wecome
contribution.
For the sake of completeness, I would mention GNU help2man[3],
as it has proved to provide fair enough manual pages out of
specially formatted --help and --version command line options
from various programs. The drawback is that it also may make
very poor manual pages if not helped a bit, and I'm not
confident of the result help2man would give out of the output
given by the help facility of argparse from the different
offpunk programs.
Also, regarding the migration script: I’ve come to the conclusion that
there should be a VERSION file in the root folder of the cache. This
file could be checked at launch and run the migration script if needed.
I agree it would be the way to go. That would make one less
manual page to maintain, and one less manual operation to carry
out as an end user.
[1]: https://lists.sr.ht/~lioploum/offpunk-packagers/%3C20230303205652.gxs6kovdqvrf5ddu%40klaus.seistrup.dk%3E
[2]: https://github.com/praiskup/argparse-manpage
[3]: https://www.gnu.org/software/help2man/
Have a nice day, :
+.+.Sh NAME+.Nm ansicat+.Nd terminal gemini gemtext renderer for offpunk+.+.Sh SYNOPSIS+.Nm+.Op Fl \-format Ar RENDERER+.Op Fl \-mime Ar MIME+.Op Fl \-url Ar URL ...+.Op Ar INPUT ...+.Nm+.Fl h | \-help+.+.Sh DESCRIPTION+Ansicat is the rendering engine of the browser+.Xr offpunk 1 .+It will render nicely on the terminal any gemtext,+html,+gopher,+and a few other formats.+.Pp+.Xr Offpunk 1+is a command-line browser and feed reader dedicated to browsing the Web,+Gemini, Gopher and Spartan.+.Ss Positional arguments+.Bl -tag -width Ds -offset indent+.It Ar INPUT+path to the text to render.+It defaults to the standard input.+.El+.Ss Keyword arguments+.Bl -tag -width Ds -offset indent+.It Fl h , \-help+show a help message and exit.+.It Fl \-format Ar RENDERER+renderer to use.+Available renderers are+.Ic auto ,+.Ic gemtext ,+.Ic html ,+.Ic feed ,+.Ic gopher ,+.Ic image ,+and+.Ic folder .+The+.Ic auto+renderer will heuristically guess the format,+either thanks to the MIME type,+or from the file being rendered itself.+.It Fl \-mime Ar MIME+MIME type of the content to parse.+.It Fl \-url Ar URL ...+original URL of the content.+.El+.+.Sh EXIT STATUS+.Ex -std+.+.Sh SEE ALSO+.Xr migrate-offpunk-cache 1 ,+.Xr netcache 1 ,+.Xr offpunk 1 ,+.Xr opnk 1 ,+.Lk https://sr.ht/~lioploum/offpunk/+.+.Sh AUTHORS+.An Lionel Dricot (Ploum) Aq Mt offpunk2 at ploum.eu
diff --git a/man/migrate-offpunk-cache.1 b/man/migrate-offpunk-cache.1
new file mode 100644
index 0000000..15696f0
--- /dev/null+++ b/man/migrate-offpunk-cache.1
@@ -0,0 +1,44 @@
+.Dd August 11, 2023+.Dt MIGRATE-OFFPUNK-CACHE 1+.Os+.+.Sh NAME+.Nm migrate-offpunk-cache+.Nd migrate offpunk cache to the newest version+.+.Sh SYNOPSIS+.Nm+.Op Ar CACHE_DIR+.Nm+.Fl h | \-help+.+.Sh DESCRIPTION+For each new version of offpunk that requires changes to the cache,+a migration function is provided.+All migration functions will be called by this script,+from the oldest to the newest version.+.Ss Positional arguments+.Bl -tag -width Ds -offset indent+.It CACHE_DIR+This is the path to the cache.+The default value will point to $XDG_CACHE_HOME,+or $HOME/.cache/offpunk if undefined.+.El+.Ss Keyword arguments+.Bl -tag -width Ds -offset indent+.It Fl h , \-help+Show a help message and exit+.El+.+.Sh EXIT STATUS+.Ex -std+.+.Sh SEE ALSO+.Xr ansicat 1 ,+.Xr netcache 1 ,+.Xr offpunk 1 ,+.Xr opnk 1 ,+.Lk https://sr.ht/~lioploum/offpunk/+.+.Sh AUTHORS+.An Lionel Dricot (Ploum) Aq Mt offpunk2 at ploum.eu
diff --git a/man/netcache.1 b/man/netcache.1
new file mode 100644
index 0000000..d17213b
--- /dev/null+++ b/man/netcache.1
@@ -0,0 +1,63 @@
+.Dd August 27, 2023+.Dt NETCACHE 1+.Os Debian+.+.Sh NAME+.Nm netcache+.Nd local Internet cache handler for offpunk+.+.Sh SYNOPSIS+.Nm+.Op Fl \-path+.Op Fl \-offline+.Op Fl \-max\-size Ar MAX_SIZE+.Op Fl \-timeout Ar TIMEOUT+.Op Ar URL ...+.Nm+.Fl h | \-help+.+.Sh DESCRIPTION+Netcache is the download and cache management engine of the browser+.Xr offpunk 1 .+It allows one to fetch a link and get its content,+writing the content through the local cache for ulterior reference.+Netcache can be forced into offline mode,+in order to only fetch resources from the local cache,+otherwise it would always refresh it from the version available online.+It is also useful for mapping a given URL to its location in the cache,+independently of whether it has been downloaded first.+.Pp+.Xr Offpunk 1+is a command-line browser and feed reader dedicated to browsing the Web,+Gemini, Gopher and Spartan.+.Ss Positional arguments+.Bl -tag -width Ds -offset indent+.It Ar URL+download the URL and output the content.+.El+.Ss Keyword arguments+.Bl -tag -width Ds -offset indent+.It Fl h , \-help+show a help message and exit.+.It Fl \-path+output the path to the cache instead of the content of the URL.+.It Fl \-max-size Ar MAX_SIZE+cancel download of items above that size.+The value is expressed in megabytes.+.It Fl \-timeout Ar TIMEOUT+time to wait before cancelling connection.+The value is expressed in seconds.+.El+.+.Sh EXIT STATUS+.Ex -std+.+.Sh SEE ALSO+.Xr ansicat 1 ,+.Xr migrate-offpunk-cache 1 ,+.Xr offpunk 1 ,+.Xr opnk 1 ,+.Lk https://sr.ht/~lioploum/offpunk/+.+.Sh AUTHORS+.An Lionel Dricot (Ploum) Aq Mt offpunk2 at ploum.eu
diff --git a/man/opnk.1 b/man/opnk.1
new file mode 100644
index 0000000..0e10214
--- /dev/null+++ b/man/opnk.1
@@ -0,0 +1,53 @@
+.Dd August 27, 2023+.Dt OPNK 1+.Os Debian+.+.Sh NAME+.Nm opnk+.Nd universal open (like a punk) for offpunk+.+.Sh SYNOPSIS+.Nm+.Op Ar INPUT ...+.Nm+.Fl h | \-help+.+.Sh DESCRIPTION+Opnk is the "universal open (like a punk)".+Opnk is a tool that will try to render any file or URL in the terminal,+using+.Xr netcache 1+and+.Xr ansicat 1 ,+and put them in+.Xr less 1 .+If that doesn’t work,+it will fallback to+.Xr xdg-open 1 .+.Pp+.Xr Offpunk 1+is a command-line browser and feed reader dedicated to browsing the Web,+Gemini, Gopher and Spartan.+.Ss Positional arguments+.Bl -tag -width Ds -offset indent+.It Ar INPUT+path to the file or URL to open.+.El+.Ss Keyword arguments+.Bl -tag -width Ds -offset indent+.It Fl h , \-help+Show a help message and exit+.El+.+.Sh EXIT STATUS+.Ex -std+.+.Sh SEE ALSO+.Xr ansicat 1 ,+.Xr migrate-offpunk-cache 1 ,+.Xr netcache 1 ,+.Xr offpunk 1 ,+.Lk https://sr.ht/~lioploum/offpunk/+.+.Sh AUTHORS+.An Lionel Dricot (Ploum) Aq Mt offpunk2 at ploum.eu
--
2.40.1
[PATCH 2/2] offpunk.1: cross reference other manual pages.
Export this patch