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
