Re: Can the documentation for Unison be migrated from the UPenn site?

Jonathan Whiteley <[email protected]> writes:

> 1. I'm using the Unison GUI v2.53.3, which appears to be the latest 
> version, on my Mac (macOS Ventura).  The Help menu contains a "Unison 
> Online Help" item, which still points to 
> https://www.cis.upenn.edu/~bcpierce/unison/docs.html, which only gives a 
> 404 error. :(  I don't know if this is something that is controlled by 
> Unison developers directly, or if someone else is creating the mac 
> binaries, but it can lead to confusion.

I think that's fixed, but if it's still wrong in the manual sources
please open an issue.

>     1. a. I installed Unison using Homebrew: entering `brew home unison` is 
> supposed to take you to the home page of the package, which currently 
> points me to "https://www.cis.upenn.edu/~bcpierce/unison/".  Perhaps 
> another pointer to update, though I suspect that's an issue with Homebrew 
> and not your direct responsibility.  I will look into updating that in the 
> homebrew formula, but I'm no expert in that area, either.

Indeed - unison's product is the source code and homebrew is responsible
for homebrew (said without malice; it's the same as pkgsrc :-).

If you download the CI artifacts, and unzip them, I think you'll find
the manual in pdf and html.

> 2. Going to the GitHub page, I had to read through most of the ReadMe file 
> to find the link to the wiki (under "Getting Unison" - but I don't want to 
> get it, I want the documentation).  The wiki page itself only contains a 
> link to the documentation folder within the GitHub repo: 
> https://urldefense.com/v3/__https://github.com/bcpierce00/unison/tree/documentation__;!!IBzWLUs!TKKI05TcpAy2SLpA7XE0sWud0s8RuGTHZ8L5qfigAjwgt-NVKHmhc3hys6W5YwWY0jSWmKDumZEeGamLWg$ .  This shows me a 
> list of files, most of which are not human-readable.  The pdf file is the 
> most convenient, but that's still 3 clicks away from the ReadMe on the 
> project page (ReadMe > wiki > documentation > pdf file). :(

The package should install the docs.   Unison the project has not
crossed into providing docs for packaging systems that install binaries
and not documentation.ppp

> 3. Reading the html file in the documentation directory on GitHub is not 
> easy.  Clicking on the file link within the project view shows the raw 
> code, which is not user-friendly.  I discovered that you can view it as a 
> regular web page by pre-pending `https://urldefense.com/v3/__https://htmlpreview.github.io/?__;!!IBzWLUs!TKKI05TcpAy2SLpA7XE0sWud0s8RuGTHZ8L5qfigAjwgt-NVKHmhc3hys6W5YwWY0jSWmKDumZH3qD7k4A$ ` to the 
> path (i.e., 
> 'https://urldefense.com/v3/__https://htmlpreview.github.io/?https:**Agithub.com*bcpierce00*unison*blob*documentation*unison-manual.html__;Ly8vLy8vLw!!IBzWLUs!TKKI05TcpAy2SLpA7XE0sWud0s8RuGTHZ8L5qfigAjwgt-NVKHmhc3hys6W5YwWY0jSWmKDumZGx4GEXWw$ ').  
> Also, there appears to be no css file to render the html version with the 
> similar look as the previous html documentation, but that's minor (and 
> perhaps intentional).  

My take is that unison being on github is a bug not a feature and my
energy, if any, would go to finding a place to migrate to.  Yes, lots of
things about github are awkward.  Plus they train proprietary AI on GPL
code -- which in my view is not ok.

> 4. There is a note on the wiki that "Release CI artifacts also include an 
> appropriate manual", but it's not clear how to find it - I assume it's 
> included in the download, but I installed unison using Homebrew, and could 
> not find a copy of the user manual in the cache or usual places. :(

Homebrew should install the docs.

> I would like to humbly request moving the link to the wiki closer to the 
> top of the ReadMe, perhaps in a separate section ("Help" or 
> "Documentation"?).

The problem is that everybody wants what they want to find first.  My
take is that people should read through; I have tried to keep it
minimal.

-- 
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].