all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Hyperlinks!
@ 2020-04-13 10:58 Ludovic Courtès
  2020-04-13 11:13 ` Hyperlinks! Pierre Neidhardt
                   ` (8 more replies)
  0 siblings, 9 replies; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-13 10:58 UTC (permalink / raw)
  To: guix-devel

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’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
@ 2020-04-13 11:13 ` Pierre Neidhardt
  2020-04-14 12:19   ` Hyperlinks! Konrad Hinsen
  2020-04-13 11:26 ` Hyperlinks! Danny Milosavljevic
                   ` (7 subsequent siblings)
  8 siblings, 1 reply; 25+ messages in thread
From: Pierre Neidhardt @ 2020-04-13 11:13 UTC (permalink / raw)
  To: Ludovic Courtès, guix-devel

[-- Attachment #1: Type: text/plain, Size: 433 bytes --]

Ludovic Courtès <ludo@gnu.org> writes:

> 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…

Perfect time for Rix, Guix in Racket!  Haha! :D

-- 
Pierre Neidhardt
https://ambrevar.xyz/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
  2020-04-13 11:13 ` Hyperlinks! Pierre Neidhardt
@ 2020-04-13 11:26 ` Danny Milosavljevic
  2020-04-13 15:10   ` Hyperlinks! Ludovic Courtès
  2020-04-13 18:09   ` Hyperlinks! Ricardo Wurmus
  2020-04-13 11:51 ` Hyperlinks! Vincent Legoll
                   ` (6 subsequent siblings)
  8 siblings, 2 replies; 25+ messages in thread
From: Danny Milosavljevic @ 2020-04-13 11:26 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

[-- Attachment #1: Type: text/plain, Size: 539 bytes --]

Hi Ludo,

On Mon, 13 Apr 2020 12:58:42 +0200
Ludovic Courtès <ludo@gnu.org> wrote:

> (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
> ‘a’, I’m all ears!)

<!DOCTYPE html>
<html>
<head>
<style>
a.syntax-symbol {
 color: red;
}
a:not(.syntax-symbol) {
 background-color: blue;
}
</style>
</head>
<body>
<p><a href="http://www.a.com/">without class</a></p>
<p><a class="syntax-symbol" href="http://www.b.com/">with class</a></p>
</body>
</html>

> Feedback welcome!

Very cool!

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
  2020-04-13 11:13 ` Hyperlinks! Pierre Neidhardt
  2020-04-13 11:26 ` Hyperlinks! Danny Milosavljevic
@ 2020-04-13 11:51 ` Vincent Legoll
  2020-04-13 11:57 ` Hyperlinks! Vincent Legoll
                   ` (5 subsequent siblings)
  8 siblings, 0 replies; 25+ messages in thread
From: Vincent Legoll @ 2020-04-13 11:51 UTC (permalink / raw)
  To: guix-devel

Hello,

On 13/04/2020 12:58, Ludovic Courtès wrote:
> 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

Wow, awesome !

I had in my todo list to create an issue about that subject.

> Hyperlinks are such an amazing invention!

Yes, definitely !

> 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…

Yes that would be very nice from a guix / guile / scheme newbie
PoV, even if not perfect.

Thanks a lot !

-- 
Vincent Legoll

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (2 preceding siblings ...)
  2020-04-13 11:51 ` Hyperlinks! Vincent Legoll
@ 2020-04-13 11:57 ` Vincent Legoll
  2020-04-13 13:48   ` Hyperlinks! Ludovic Courtès
  2020-04-13 12:05 ` Hyperlinks! Vincent Legoll
                   ` (4 subsequent siblings)
  8 siblings, 1 reply; 25+ messages in thread
From: Vincent Legoll @ 2020-04-13 11:57 UTC (permalink / raw)
  To: guix-devel

1st bug report ? :P

OK, not strictly a bug report since it's on the
wrong ML...

on the page:
https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html

The %base-packages is not cross-referenced,
whereas all the other %base-* are.

Should I create an issue for it ?

-- 
Vincent Legoll

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (3 preceding siblings ...)
  2020-04-13 11:57 ` Hyperlinks! Vincent Legoll
@ 2020-04-13 12:05 ` Vincent Legoll
  2020-04-13 13:56   ` Hyperlinks! Ludovic Courtès
  2020-04-13 15:59 ` Hyperlinks! Christopher Baines
                   ` (3 subsequent siblings)
  8 siblings, 1 reply; 25+ messages in thread
From: Vincent Legoll @ 2020-04-13 12:05 UTC (permalink / raw)
  To: guix-devel

I see there are "#index${SOMETHING}" url suffixes,

What about adding anchors like on:

https://docs.python.org/3/library/functions.html#eval

when you mouse-over the function name line, a
"permalink to this definition" appears.

I often want to give pointers to specific parts of the
doc, and did not know about the #index thing (or
maybe it is just being introduced). I think a visual
thing like in the python doc would be nice to add...

Should I create an issue about this ?

-- 
Vincent Legoll

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 11:57 ` Hyperlinks! Vincent Legoll
@ 2020-04-13 13:48   ` Ludovic Courtès
  2020-04-13 13:51     ` Hyperlinks! Vincent Legoll
  0 siblings, 1 reply; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-13 13:48 UTC (permalink / raw)
  To: Vincent Legoll; +Cc: guix-devel

Hi,

Vincent Legoll <vincent.legoll@gmail.com> skribis:

> 1st bug report ? :P
>
> OK, not strictly a bug report since it's on the
> wrong ML...
>
> on the page:
> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
>
> The %base-packages is not cross-referenced,
> whereas all the other %base-* are.

That’s because there’s no @defvr (variable definition) in the manual for
‘%base-packages’.

> Should I create an issue for it ?

Just send a patch adding a @defvr for %base-packages.  :-)

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 13:48   ` Hyperlinks! Ludovic Courtès
@ 2020-04-13 13:51     ` Vincent Legoll
  0 siblings, 0 replies; 25+ messages in thread
From: Vincent Legoll @ 2020-04-13 13:51 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

Hello,

On 13/04/2020 15:48, Ludovic Courtès wrote:
> Vincent Legoll <vincent.legoll@gmail.com> skribis:
>
>> 1st bug report ? :P
>>
>> OK, not strictly a bug report since it's on the
>> wrong ML...
>>
>> on the page:
>> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
>>
>> The %base-packages is not cross-referenced,
>> whereas all the other %base-* are.
> That’s because there’s no @defvr (variable definition) in the manual for
> ‘%base-packages’.
>
>> Should I create an issue for it ?
> Just send a patch adding a @defvr for %base-packages.  :-)

I've seen other similar issues, let's see if I can manage to fix
them myself...

-- 
Vincent Legoll

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 12:05 ` Hyperlinks! Vincent Legoll
@ 2020-04-13 13:56   ` Ludovic Courtès
  2020-04-13 14:41     ` Hyperlinks! Danny Milosavljevic
  0 siblings, 1 reply; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-13 13:56 UTC (permalink / raw)
  To: Vincent Legoll; +Cc: guix-devel

Vincent Legoll <vincent.legoll@gmail.com> skribis:

> I see there are "#index${SOMETHING}" url suffixes,
>
> What about adding anchors like on:
>
> https://docs.python.org/3/library/functions.html#eval

There are already anchors, but they look like #index-procedure.

> when you mouse-over the function name line, a
> "permalink to this definition" appears.

I’m not sure how to do that.  Isn’t there some JavaScript involved?

> I often want to give pointers to specific parts of the
> doc, and did not know about the #index thing (or
> maybe it is just being introduced). I think a visual
> thing like in the python doc would be nice to add...
>
> Should I create an issue about this ?

Sure, if you want.

The bottom line is that this is all very much a hack: we’re
post-processing generated HTML that we have no control over.
Longer-term, it would be nicer to use Guile’s stexi modules all along
with tight control over the generated HTML.

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 13:56   ` Hyperlinks! Ludovic Courtès
@ 2020-04-13 14:41     ` Danny Milosavljevic
  2020-04-13 14:45       ` Hyperlinks! Danny Milosavljevic
  0 siblings, 1 reply; 25+ messages in thread
From: Danny Milosavljevic @ 2020-04-13 14:41 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

[-- Attachment #1: Type: text/plain, Size: 519 bytes --]

Hi Ludo,

On Mon, 13 Apr 2020 15:56:22 +0200
Ludovic Courtès <ludo@gnu.org> wrote:

> > when you mouse-over the function name line, a
> > "permalink to this definition" appears.  
> 
> I’m not sure how to do that.  Isn’t there some JavaScript involved?

The CSS selector ":hover" selects the block only when you are hovering over it:

a[name] img {
  display: none;
}

a[name]:hover img {
  display: inline;
}

Used like that:

<p><a name="anchor1">with class <img src="a.png"></a>
...</p>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 14:41     ` Hyperlinks! Danny Milosavljevic
@ 2020-04-13 14:45       ` Danny Milosavljevic
  0 siblings, 0 replies; 25+ messages in thread
From: Danny Milosavljevic @ 2020-04-13 14:45 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

[-- Attachment #1: Type: text/plain, Size: 272 bytes --]

Or

 visibility: hidden

instead of

 display: none

and

  visibility: visible

instead of

  display: inline

if we don't want the actual layout to change (probably a good idea not to
recompute the layout every time someone hovers over something :) ).

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 11:26 ` Hyperlinks! Danny Milosavljevic
@ 2020-04-13 15:10   ` Ludovic Courtès
  2020-04-13 15:25     ` Hyperlinks! Julien Lepiller
  2020-04-13 18:09   ` Hyperlinks! Ricardo Wurmus
  1 sibling, 1 reply; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-13 15:10 UTC (permalink / raw)
  To: Danny Milosavljevic; +Cc: guix-devel

Hi,

Danny Milosavljevic <dannym@scratchpost.org> skribis:

> a:not(.syntax-symbol) {
>  background-color: blue;
> }

Nice!  It works, but I’d have to spread “not(.syntax-symbol)” in CSS
files that shouldn’t know about ‘syntax-symbol’ in the first place.

Is there a way to somehow have an ‘a.syntax-symbol’ rule take precedence
over other ‘a’ rules?

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 15:10   ` Hyperlinks! Ludovic Courtès
@ 2020-04-13 15:25     ` Julien Lepiller
  0 siblings, 0 replies; 25+ messages in thread
From: Julien Lepiller @ 2020-04-13 15:25 UTC (permalink / raw)
  To: guix-devel

Le 13 avril 2020 11:10:32 GMT-04:00, "Ludovic Courtès" <ludo@gnu.org> a écrit :
>Hi,
>
>Danny Milosavljevic <dannym@scratchpost.org> skribis:
>
>> a:not(.syntax-symbol) {
>>  background-color: blue;
>> }
>
>Nice!  It works, but I’d have to spread “not(.syntax-symbol)” in CSS
>files that shouldn’t know about ‘syntax-symbol’ in the first place.
>
>Is there a way to somehow have an ‘a.syntax-symbol’ rule take
>precedence
>over other ‘a’ rules?
>
>Thanks,
>Ludo’.

The a.syntax-symbol is more specific that the a rule, so it already takes precedence. You can use this to reset a value:

a {
  backgraound-color: blue;
}

a.syntak-symbol {
  background-color: inherit /*or none*/ ;
}

Of course some a tags might be styled with more specific rules, so you have to make sure your rule is evn more specific. Alternatively use !important, which is considered bad practice.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (4 preceding siblings ...)
  2020-04-13 12:05 ` Hyperlinks! Vincent Legoll
@ 2020-04-13 15:59 ` Christopher Baines
  2020-04-13 16:22 ` Hyperlinks! sirgazil
                   ` (2 subsequent siblings)
  8 siblings, 0 replies; 25+ messages in thread
From: Christopher Baines @ 2020-04-13 15:59 UTC (permalink / raw)
  To: guix-devel

[-- Attachment #1: Type: text/plain, Size: 419 bytes --]


Ludovic Courtès <ludo@gnu.org> writes:

> 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!

This is indeed amazing!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 962 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (5 preceding siblings ...)
  2020-04-13 15:59 ` Hyperlinks! Christopher Baines
@ 2020-04-13 16:22 ` sirgazil
  2020-04-14  7:09 ` Hyperlinks! Bengt Richter
  2020-04-14 18:41 ` Hyperlinks! Christopher Lemmer Webber
  8 siblings, 0 replies; 25+ messages in thread
From: sirgazil @ 2020-04-13 16:22 UTC (permalink / raw)
  To: "Ludovic Courtès"; +Cc: guix-devel

 ---- On Mon, 13 Apr 2020 10:58:42 +0000 Ludovic Courtès <ludo@gnu.org> 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!

That's great.


 > (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
 > ‘a’, I’m all ears!)

I think to style links you should be using the pseudo classes like ":link", ":hover", ":visited", etc. So, for example:

a.syntax-symbol:link {
    color: black;
}

If I understand correctly, that should work.

 > 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 still don't understand why Texinfo doesn't provide syntax for allowing the HTML exporter to do that... Something like a @codeblock that accepts a language argument...

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 11:26 ` Hyperlinks! Danny Milosavljevic
  2020-04-13 15:10   ` Hyperlinks! Ludovic Courtès
@ 2020-04-13 18:09   ` Ricardo Wurmus
  2020-04-13 18:38     ` Hyperlinks! Danny Milosavljevic
  1 sibling, 1 reply; 25+ messages in thread
From: Ricardo Wurmus @ 2020-04-13 18:09 UTC (permalink / raw)
  To: guix-devel


Danny Milosavljevic <dannym@scratchpost.org> writes:

> On Mon, 13 Apr 2020 12:58:42 +0200
> Ludovic Courtès <ludo@gnu.org> wrote:
>
>> (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
>> ‘a’, I’m all ears!)
[…]
> a.syntax-symbol {
>  color: red;
> }
> a:not(.syntax-symbol) {
>  background-color: blue;
> }

The first definition would suffice if it came after any style definition
for just “a”.

If this doesn’t work it would be because a more specific rule exists
(e.g. “.example div.foo span.bar a”); in that case you just need to
define a *more* specific style rule.

--
Ricardo

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 18:09   ` Hyperlinks! Ricardo Wurmus
@ 2020-04-13 18:38     ` Danny Milosavljevic
  2020-04-13 21:05       ` Hyperlinks! Ricardo Wurmus
  0 siblings, 1 reply; 25+ messages in thread
From: Danny Milosavljevic @ 2020-04-13 18:38 UTC (permalink / raw)
  To: Ricardo Wurmus; +Cc: guix-devel

[-- Attachment #1: Type: text/plain, Size: 996 bytes --]

Hi Ricardo,

On Mon, 13 Apr 2020 20:09:26 +0200
Ricardo Wurmus <rekado@elephly.net> wrote:

> Danny Milosavljevic <dannym@scratchpost.org> writes:
> 
> > On Mon, 13 Apr 2020 12:58:42 +0200
> > Ludovic Courtès <ludo@gnu.org> wrote:
> >  
> >> (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
> >> ‘a’, I’m all ears!)  
> […]
> > a.syntax-symbol {
> >  color: red;
> > }
> > a:not(.syntax-symbol) {
> >  background-color: blue;
> > }  
> 
> The first definition would suffice if it came after any style definition
> for just “a”.

Yeah, but the behavior would be different.

I thought Ludo meant that he wanted the rules for just "a" not to apply to
"a.syntax-symbol".  With your version the rules for just "a" and the ones
for "a.syntax-symbol" would totally both apply to "a.syntax-symbol"s.

In my version, the "with class" text doesn't have a blue background.
In yours, it would have.

(I'd agree that it's often overkill)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 18:38     ` Hyperlinks! Danny Milosavljevic
@ 2020-04-13 21:05       ` Ricardo Wurmus
  2020-04-13 21:15         ` Hyperlinks! Danny Milosavljevic
  0 siblings, 1 reply; 25+ messages in thread
From: Ricardo Wurmus @ 2020-04-13 21:05 UTC (permalink / raw)
  To: Danny Milosavljevic; +Cc: guix-devel


Danny Milosavljevic <dannym@scratchpost.org> writes:

> Hi Ricardo,
>
> On Mon, 13 Apr 2020 20:09:26 +0200
> Ricardo Wurmus <rekado@elephly.net> wrote:
>
>> Danny Milosavljevic <dannym@scratchpost.org> writes:
>> 
>> > On Mon, 13 Apr 2020 12:58:42 +0200
>> > Ludovic Courtès <ludo@gnu.org> wrote:
>> >  
>> >> (If anyone knows how to get ‘a.syntax-symbol’ CSS different from just
>> >> ‘a’, I’m all ears!)  
>> […]
>> > a.syntax-symbol {
>> >  color: red;
>> > }
>> > a:not(.syntax-symbol) {
>> >  background-color: blue;
>> > }  
>> 
>> The first definition would suffice if it came after any style definition
>> for just “a”.
>
> Yeah, but the behavior would be different.
>
> I thought Ludo meant that he wanted the rules for just "a" not to apply to
> "a.syntax-symbol".  With your version the rules for just "a" and the ones
> for "a.syntax-symbol" would totally both apply to "a.syntax-symbol"s.
>
> In my version, the "with class" text doesn't have a blue background.
> In yours, it would have.
>
> (I'd agree that it's often overkill)

Oh, thanks for the clarification.  I must have misunderstood Ludo’s request.

-- 
Ricardo

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 21:05       ` Hyperlinks! Ricardo Wurmus
@ 2020-04-13 21:15         ` Danny Milosavljevic
  2020-04-13 21:25           ` Hyperlinks! Ludovic Courtès
  0 siblings, 1 reply; 25+ messages in thread
From: Danny Milosavljevic @ 2020-04-13 21:15 UTC (permalink / raw)
  To: Ricardo Wurmus; +Cc: guix-devel

[-- Attachment #1: Type: text/plain, Size: 272 bytes --]

Hi Ricardo,

On Mon, 13 Apr 2020 23:05:00 +0200
Ricardo Wurmus <rekado@elephly.net> wrote:

> Oh, thanks for the clarification.  I must have misunderstood Ludo’s request.

No, it's totally possible that he meant it like you meant it.

Thanks for your version!

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 21:15         ` Hyperlinks! Danny Milosavljevic
@ 2020-04-13 21:25           ` Ludovic Courtès
  0 siblings, 0 replies; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-13 21:25 UTC (permalink / raw)
  To: Danny Milosavljevic; +Cc: guix-devel

Hi!

Thanks all for the clarifications!  I’ve pushed an update to ‘code.css’
that gives me the result I wanted (should show up on-line soonish, just
reload the page).

Ludo’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (6 preceding siblings ...)
  2020-04-13 16:22 ` Hyperlinks! sirgazil
@ 2020-04-14  7:09 ` Bengt Richter
  2020-04-14  8:27   ` Hyperlinks! pelzflorian (Florian Pelz)
  2020-04-14 18:41 ` Hyperlinks! Christopher Lemmer Webber
  8 siblings, 1 reply; 25+ messages in thread
From: Bengt Richter @ 2020-04-14  7:09 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-14  7:09 ` Hyperlinks! Bengt Richter
@ 2020-04-14  8:27   ` pelzflorian (Florian Pelz)
  2020-04-14 10:34     ` Hyperlinks! Ludovic Courtès
  0 siblings, 1 reply; 25+ messages in thread
From: pelzflorian (Florian Pelz) @ 2020-04-14  8:27 UTC (permalink / raw)
  To: Bengt Richter; +Cc: guix-devel

On Tue, Apr 14, 2020 at 09:09:24AM +0200, Bengt Richter wrote:
> 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 ;-).
> 

https://guix.gnu.org/manual-devel/

currently contains new stuff like the earlyoom service , while

https://guix.gnu.org/manual/

does not.  I do not know what the plan for these is though.

Regards,
Florian

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-14  8:27   ` Hyperlinks! pelzflorian (Florian Pelz)
@ 2020-04-14 10:34     ` Ludovic Courtès
  0 siblings, 0 replies; 25+ messages in thread
From: Ludovic Courtès @ 2020-04-14 10:34 UTC (permalink / raw)
  To: pelzflorian (Florian Pelz); +Cc: guix-devel

Hi,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

> https://guix.gnu.org/manual-devel/

I’m surprised this URL works; should be
<https://guix.gnu.org/manual/devel/>.

> currently contains new stuff like the earlyoom service , while
>
> https://guix.gnu.org/manual/
>
> does not.  I do not know what the plan for these is though.

/manual refers to the latest release.  This is so that the information
corresponds to the release that people download (in particular the
installation instructions).

Note that every time you run “guix pull”, you fetch an up-to-date copy
of the manual that can be browsed with ‘info’ or Emacs.  That’s still
the best way to ensure you’re reading a manual that corresponds to the
Guix you have.

Ludo’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 11:13 ` Hyperlinks! Pierre Neidhardt
@ 2020-04-14 12:19   ` Konrad Hinsen
  0 siblings, 0 replies; 25+ messages in thread
From: Konrad Hinsen @ 2020-04-14 12:19 UTC (permalink / raw)
  To: guix-devel

On 13/04/2020 13:13, Pierre Neidhardt wrote:
> Ludovic Courtès <ludo@gnu.org> writes:
>
>> 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…
> Perfect time for Rix, Guix in Racket!  Haha! :D

Easy. "Just" implement #lang guile in Racket ;-)


Cheers,

   Konrad.

^ permalink raw reply	[flat|nested] 25+ messages in thread

* Re: Hyperlinks!
  2020-04-13 10:58 Hyperlinks! Ludovic Courtès
                   ` (7 preceding siblings ...)
  2020-04-14  7:09 ` Hyperlinks! Bengt Richter
@ 2020-04-14 18:41 ` Christopher Lemmer Webber
  8 siblings, 0 replies; 25+ messages in thread
From: Christopher Lemmer Webber @ 2020-04-14 18:41 UTC (permalink / raw)
  To: guix-devel

This is very nice.  The rainbow parenthesis matching is really excellent
too.

Guix has managed to make Texinfo html export look really nice!  I admit
I expressed skepticism in this endeavour a number of years back and am
happy to be incorrect.


Ludovic Courtès writes:

> 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’.

^ permalink raw reply	[flat|nested] 25+ messages in thread

end of thread, other threads:[~2020-04-14 18:41 UTC | newest]

Thread overview: 25+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-04-13 10:58 Hyperlinks! Ludovic Courtès
2020-04-13 11:13 ` Hyperlinks! Pierre Neidhardt
2020-04-14 12:19   ` Hyperlinks! Konrad Hinsen
2020-04-13 11:26 ` Hyperlinks! Danny Milosavljevic
2020-04-13 15:10   ` Hyperlinks! Ludovic Courtès
2020-04-13 15:25     ` Hyperlinks! Julien Lepiller
2020-04-13 18:09   ` Hyperlinks! Ricardo Wurmus
2020-04-13 18:38     ` Hyperlinks! Danny Milosavljevic
2020-04-13 21:05       ` Hyperlinks! Ricardo Wurmus
2020-04-13 21:15         ` Hyperlinks! Danny Milosavljevic
2020-04-13 21:25           ` Hyperlinks! Ludovic Courtès
2020-04-13 11:51 ` Hyperlinks! Vincent Legoll
2020-04-13 11:57 ` Hyperlinks! Vincent Legoll
2020-04-13 13:48   ` Hyperlinks! Ludovic Courtès
2020-04-13 13:51     ` Hyperlinks! Vincent Legoll
2020-04-13 12:05 ` Hyperlinks! Vincent Legoll
2020-04-13 13:56   ` Hyperlinks! Ludovic Courtès
2020-04-13 14:41     ` Hyperlinks! Danny Milosavljevic
2020-04-13 14:45       ` Hyperlinks! Danny Milosavljevic
2020-04-13 15:59 ` Hyperlinks! Christopher Baines
2020-04-13 16:22 ` Hyperlinks! sirgazil
2020-04-14  7:09 ` Hyperlinks! Bengt Richter
2020-04-14  8:27   ` Hyperlinks! pelzflorian (Florian Pelz)
2020-04-14 10:34     ` Hyperlinks! Ludovic Courtès
2020-04-14 18:41 ` Hyperlinks! Christopher Lemmer Webber

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.