[Nut-upsdev] Documentation inside git

[Jim Klimov]

Huh, they (GH) did add support for "latest release" artifacts, just the URL
was a bit more complex:
https://github.com/networkupstools/ConfigExamples/releases/latest/downloads/ConfigExamples.pdf

In the meanwhile, I've added/updated Roger's scripts from
http://rogerprice.org/NUT into git repos:
* https://github.com/networkupstools/ConfigExamples/tree/master/scripts for
newly hosted copies of nut-journal and nut-report
* https://github.com/networkupstools/TLS-UPSmon and
https://github.com/networkupstools/TLS-Shims which we started earlier

Now working on updating the links from nut website (technically
nut::docs/documentation.txt for this page)

Jim

On Mon, Jun 3, 2024 at 11:02 AM Jim Klimov <jimklimov+nut at gmail.com> wrote:

> Now back to computers - so re-checked some bits.
>
> The existing https://networkupstools.org/documentation.html page offers
> currently the
> https://github.com/networkupstools/ConfigExamples/releases/latest/ URL as
> "NUT Configuration Examples
> <https://github.com/networkupstools/ConfigExamples/releases/latest> book
> maintained by Roger Price"
>
> This in turn redirects to a particular newest release page, "beknownst to
> GitHub but unbeknownst to us" externally (paraphrasing Starballs, credit
> where due), and so the browser ends up at
> https://github.com/networkupstools/ConfigExamples/releases/tag/book-3.0-20230319-nut-2.8.0
> page currently, and the rendered book is available there as
> https://github.com/networkupstools/ConfigExamples/releases/download/book-3.0-20230319-nut-2.8.0/ConfigExamples.pdf
>
> I've tried requesting
> https://github.com/networkupstools/ConfigExamples/releases/latest/ConfigExamples.pdf
> but it does not auto-redirect to a newest release (as of the day of user's
> request from their browser).
>
> There is a Makefile in the book repository
> https://github.com/networkupstools/ConfigExamples/tree/master but no
> further continuous integration recipes - so the book releases were built
> and uploaded to github manually after all.
>
> At the moment a "seamless-browsing" way forward can be to discover the
> release PDF URL when building the nut-website, and embed that string into
> the documentation page (alternately - keep a copy of that PDF in the
> rendered website repo, like we keep user/dev manuals). One downside is that
> this reference would not direct the user to a newer PDF if/when the book
> marches on with new releases, at least not until the nut-website is
> rebuilt. This is likely not a big constraint in practice, given how the
> master version of the site is rebuilt with each new merged PR, and the book
> is updated much less frequently.
>
> Technically, the website build job runs several times a day but usually
> detects there is nothing to do so aborts quickly. Detection of a new book
> release (or even commit in its repo, so we can `make` it into a PDF) can be
> a trigger to proceed with the build even if other sources did not change.
>
> FWIW, I've also noticed that "NUT Setup with openSUSE
> <http://rogerprice.org/NUT.html> *(Roger Price)*" link from
> https://networkupstools.org/documentation.html goes to
> http://rogerprice.org/NUT.html which is AWOL, but there is now an
> http://rogerprice.org/NUT (without an extension) with the OpenSUSE page
> mentioned as retired.
>
> Jim
>
>
> On Mon, Jun 3, 2024 at 7:55 AM Jim Klimov <jimklimov+nut at gmail.com> wrote:
>
>> The pieces should all be there, I think.
>>
>> NUT source iterations cooperate with the sister nut-website repo on
>> github, as well as nut-ddl and some more, to produce an horde of static
>> HTML pages, and PDF versions of some docs, tarballs, etc. which are pushed
>> to a repo for "github pages" and with their magic (I guess GH spins up a
>> container with a web server and many data files for each new commit on this
>> pages repo) they become a browsable statically rendered site, as Greg
>> outlined.
>>
>> A model case for "browsable" PDF files embedded here are NUT's User and
>> Developer manuals, or the Changelog.
>>
>> Likewise, a couple of years back we made Roger's book sources into a
>> GitHub repo (should be complete with a Makefile to render it, don't quite
>> remember if I had any further CI to react to commits or tagged releases, or
>> I built the PDFs locally and uploaded as release artifacts), and it was
>> updated a couple of times since.
>>
>> So maybe the quest is about changing the link style from the nut-website
>> renditions to the book's PDF, so it would by default open in the same tab?
>>
>> Currently commuting so can't say more at the moment.
>>
>> Jim
>>
>> On Mon, Jun 3, 2024, 02:21 Greg Troxel via Nut-upsdev <
>> nut-upsdev at alioth-lists.debian.net> wrote:
>>
>>> Roger Price <roger at rogerprice.org> writes:
>>>
>>> > On Sun, 2 Jun 2024, Jim Klimov wrote:
>>> >
>>> >> Trying to remember the context: is your book only rendered as a PDF
>>> >> (a "release" of which on GitHub the NUT site currently points to),
>>> >> or are there also HTML renditions to point to this way (to see in a
>>> >> typical browser)?
>>> >
>>> > Sorry, I did not express myself clearly.  The book is in PDF, but PDF
>>> > can be displayed as if it were HTML by browsers such as Firefox and
>>> > Opera.  These browsers and maybe others are capable of treating PDF
>>> > just like it was HTML and providing an immediate display.
>>>
>>> Not really, but they will run a js program to render pdf.  Which means
>>> the user sees it, similar to html, so I see your point.
>>>
>>> > I would like to have an immediate display of the book from the NUT
>>> > website rather than from my own.  I think it's better to point
>>> > visitors to our official site rather than a personal site.  Also, NUT
>>> > will around a lot longer than me and my site, and maybe the book would
>>> > still be usefull.
>>>
>>> I think it still needs a CI rule to build the pdf and put it on github
>>> pages, or some other way to get it on whatever networkupstools.org is,
>>> and for that I think we'll need to wait for Jim.
>>>
>>> _______________________________________________
>>> Nut-upsdev mailing list
>>> Nut-upsdev at alioth-lists.debian.net
>>> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20240603/d99b7f5b/attachment.htm>