From mboxrd@z Thu Jan 1 00:00:00 1970 From: Bengt Richter Subject: Re: Hyperlinks! Date: Tue, 14 Apr 2020 09:09:24 +0200 Message-ID: <20200414070924.GA2509@LionPure> References: <87eesrlkil.fsf@gnu.org> Reply-To: Bengt Richter Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:41977) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jOFhd-0000aP-N7 for guix-devel@gnu.org; Tue, 14 Apr 2020 03:09:50 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jOFhc-0007h2-20 for guix-devel@gnu.org; Tue, 14 Apr 2020 03:09:49 -0400 Content-Disposition: inline In-Reply-To: <87eesrlkil.fsf@gnu.org> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane-mx.org@gnu.org Sender: "Guix-devel" To: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: guix-devel@gnu.org Hi Ludo, On +2020-04-13 12:58:42 +0200, Ludovic Court=C3=A8s wrote: > Hello Guix! >=20 > Scheme code snippets in the on-line manual now have hyperlinks for all > the symbols documented in the manual: >=20 > https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuratio= n-System.html > https://guix.gnu.org/manual/devel/en/html_node/Defining-Packages.html >=20 > Hyperlinks are such an amazing invention! >=20 > (If anyone knows how to get =E2=80=98a.syntax-symbol=E2=80=99 CSS diffe= rent from just > =E2=80=98a=E2=80=99, I=E2=80=99m all ears!) >=20 > This is happening in =E2=80=98doc/build.scm=E2=80=99 as a post-processi= ng 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=E2=80=94e.g., anytime =E2=80=9Cservice=E2=80=9D appears, it=E2=80= =99ll link to the =E2=80=98service=E2=80=99 > procedure. >=20 > I=E2=80=99d like to extend it to include references to the Guile manual= , so that > one could click on, say, =E2=80=98append=E2=80=99, but there might be t= oo many false > positives at that point. And then we would need DrRacket fanciness to > be able to determine what an identifier really refers to=E2=80=A6 >=20 > Feedback welcome! >=20 > Ludo=E2=80=99. >=20 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 depende= nt on secondary external links. (Or people might be tempted to wget [options intentionally absent ;-] 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=3Dguix.git;a=3Dblob;f=3Ddoc/guix.t= exi;h=3D891e2693f66672fc309b510ee2a5a4d5dd737db0;hb=3D8c04471f2403f05bcbe= a740e3722030e2b8311ec (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 we= b 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 h= ave the latest docs without downloading the rest (or disturbing a current state), to read off= line? 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 gui= x on old review pages or by following links from old stuff to old stuff, and may c= onclude 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=C2=A2 ;-) --=20 Regards, Bengt Richter