Re: Hyperlinks!

[Bengt Richter <bokr@bokr.com>]

Hi Ludo,

On +2020-04-13 12:58:42 +0200, Ludovic Courtès wrote:
> Hello Guix!
> 
> Scheme code snippets in the on-line manual now have hyperlinks for all
> the symbols documented in the manual:
> 
>   https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
>   https://guix.gnu.org/manual/devel/en/html_node/Defining-Packages.html
> 
> Hyperlinks are such an amazing invention!
> 
> (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
> ‘a’, I’m all ears!)
> 
> This is happening in ‘doc/build.scm’ as a post-processing step on the
> makeinfo-generated HTML (along with the syntax-highlighting
> post-processing step).  It works well but there can be false positives
> because it matches on identifiers, without taking scope etc. into
> account—e.g., anytime “service” appears, it’ll link to the ‘service’
> procedure.
> 
> I’d like to extend it to include references to the Guile manual, so that
> one could click on, say, ‘append’, but there might be too many false
> positives at that point.  And then we would need DrRacket fanciness to
> be able to determine what an identifier really refers to…
> 
> Feedback welcome!
> 
> Ludo’.
> 

I think it important to have a very up-to-date version of docs
that can be downloaded like the single-page html doc alternatives
usually offered on gnu.org, for off-line use, and not have it too dependent
on secondary external links. (Or people might be tempted to
wget [options intentionally absent ;-] <an index page> to get more
to read off-line ;-).

Is https://guix.gnu.org/manual/en/guix.html in really good sync with
https://git.savannah.gnu.org/gitweb/?p=guix.git;a=blob;f=doc/guix.texi;h=891e2693f66672fc309b510ee2a5a4d5dd737db0;hb=8c04471f2403f05bcbea740e3722030e2b8311ec

(what's the easiest way to check? firefox page-info for
https://guix.gnu.org/manual/en/guix.html says
Modified: January 1, 1970, 1:00:01 AM GMT+1 ;-)

I like being able to do a git pull to get an updated version of a project
so I can trust it represents the latest official output from there.

But I like to read about a new project before I download the whole thing.
I prefer what I can believe is the latest official docs, not years-old web search results.
So I'll look for a git repo that I can browse for docs, preferring nicely hyperlinked ones.

I apppreciate not having to work to get tex or texi converted (as mostly happens
with package installs), but what if I (or a non-guix-user) just want to have the latest docs
without downloading the rest (or disturbing a current state), to read offline?
I think for that, pre-built single-page html should be available, please :)

If the latest is not easily available, people are likely to encounter guix on old
review pages or by following links from old stuff to old stuff, and may conclude
that guix is not even near ready for prime-time.

I think up-to-date wikipedia links are important, as people may go there out of interest
sparked elsewhere, to get up-to-date info on guix.
Is updating wikipedia part of guix documentation work-flow?

My 2¢ ;-)

-- 
Regards,
Bengt Richter