[Nut-upsdev] Documentation inside git

[Jim Klimov]

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/cfb2c172/attachment-0001.htm>