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.
Signed-off-by: Étienne Mollier <emollier@debian.org>
---
man/ansicat.1 | 72 +++++++++++++++++++++++++++++++++++++man/migrate-offpunk-cache.1 | 44 +++++++++++++++++++++++man/netcache.1 | 63 ++++++++++++++++++++++++++++++++man/opnk.1 | 53 +++++++++++++++++++++++++++
4 files changed, 232 insertions(+)
create mode 100644 man/ansicat.1
create mode 100644 man/migrate-offpunk-cache.1
create mode 100644 man/netcache.1
create mode 100644 man/opnk.1
diff --git a/man/ansicat.1 b/man/ansicat.1
new file mode 100644
index 0000000..042a449
--- /dev/null+++ b/man/ansicat.1
@@ -0,0 +1,72 @@
+.Dd August 27, 2023+.Dt ANSICAT 1+.Os Debian+.+.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.
On 23/08/27 10:33, Étienne Mollier wrote:
>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?
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.
Sotiris, what do you think?
Hi phoebos,
phoebos, on 2023-08-28:
> On Sun, Aug 27, 2023 at 22:33:50 +0200, Étienne Mollier wrote:> > +.Os Debian> > Not sure you meant to include these.
Gosh, my evil plan to conquer the world with Debian is busted!
You're quite right, according to groff_mdoc(7) and my subsequent
test, if the field is left blank, then the manual pages engine
will fill it automatically. So I'm certain I don't want include
these.
Thank you for your rereading, :)
--
.''`. Étienne Mollier <emollier@debian.org>
: :' : gpg: 8f91 b227 c7d6 f2b1 948c 8236 793c f67e 8f0d 11da
`. `' sent from /dev/pts/1, please excuse my verbosity
`- on air: Tangerine Dream - Phaedra (Steven Wilson 2018 …
On 23/08/28 10:32, Étienne Mollier wrote:
>Hi phoebos,>>phoebos, on 2023-08-28:>> On Sun, Aug 27, 2023 at 22:33:50 +0200, Étienne Mollier wrote:>> > +.Os Debian>>>> Not sure you meant to include these.>>Gosh, my evil plan to conquer the world with Debian is busted!>>You're quite right, according to groff_mdoc(7) and my subsequent>test, if the field is left blank, then the manual pages engine>will fill it automatically. So I'm certain I don't want include>these.
Should I just remove those lines?
Hi Ploum,
Ploum, on 2023-08-27:
> 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.
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, :)
--
.''`. Étienne Mollier <emollier@debian.org>
: :' : gpg: 8f91 b227 c7d6 f2b1 948c 8236 793c f67e 8f0d 11da
`. `' sent from /dev/pts/1, please excuse my verbosity
`-
Ploum, on 2023-08-28:
> On 23/08/28 10:32, Étienne Mollier wrote:>>Hi phoebos,>>>>phoebos, on 2023-08-28:>>> On Sun, Aug 27, 2023 at 22:33:50 +0200, Étienne Mollier wrote:>>> > +.Os Debian>>>>>> Not sure you meant to include these.>>>>Gosh, my evil plan to conquer the world with Debian is busted!>>>>You're quite right, according to groff_mdoc(7) and my subsequent>>test, if the field is left blank, then the manual pages engine>>will fill it automatically. So I'm certain I don't want include>>these.> > Should I just remove those lines?
The following, with the field left blank, should do:
+.Os
Cheers, :)
--
.''`. Étienne Mollier <emollier@debian.org>
: :' : gpg: 8f91 b227 c7d6 f2b1 948c 8236 793c f67e 8f0d 11da
`. `' sent from /dev/pts/2, please excuse my verbosity
`- on air: Wolverine - Sleepy Town
On 2023-08-27, Ploum wrote:
>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.>>Sotiris, what do you think?
Sounds good to me! Maybe something like a .version file in the cache
root containing an offpunk version number, e.g. 1.10.0. Offpunk attempts
to read the file on startup:
* If the file doesn't exist, offpunk creates it and runs all migration
commands.
* If the version in the file is smaller than the current offpunk
version, all (or maybe only relevant) migration commands are run and
the current offpunk version is written in the file.
Best,
Sotiris
On 23/08/29 10:44, Sotiris Papatheodorou wrote:
>On 2023-08-27, Ploum wrote:>>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.>>>>Sotiris, what do you think?>>Sounds good to me! Maybe something like a .version file in the cache >root containing an offpunk version number, e.g. 1.10.0. Offpunk >attempts to read the file on startup:>>* If the file doesn't exist, offpunk creates it and runs all migration >commands.>* If the version in the file is smaller than the current offpunk >version, all (or maybe only relevant) migration commands are run and >the current offpunk version is written in the file.
I’ve implemented that but with a simple integer as the cache version
which is independant from offpunk version.
This is implemented in offutils.py in order to be run the first time the
CACHE_PATH variable is requested.
Migration scripts should now be implemented in cache_migration.py and
should be called "upgrade_to_X" where X is an integer representing the
target version.
Review of the code is welcome
(the man page for the migration script has been removed)
On 23/08/28 11:06, Étienne Mollier wrote:
>Hi Ploum,>>Ploum, on 2023-08-27:>> 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.
On 2023-08-29, Ploum wrote:
>I’ve implemented that but with a simple integer as the cache version>which is independant from offpunk version.
Even simpler, fine by me.
On 2023-08-29, Ploum wrote:
>Review of the code is welcome
Had a quick look and all seems well!
Best,
Sotiris