Nicer looking Info - Re: html manual +css

Nicer looking Info - Re: html manual +css

[ndame]

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


> I have eventually resumed "work" on this and here is what I got:
> 
> Original:
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Visiting-Functions.html
> 
> Sample:
> https://brandelune.github.io/code/Visiting-Functions.html

Don't you plan to apply similar changes to the built in Info?

Its current styling is pretty bare bones, styling like above could
make it much more pleasant to read:

https://i.imgur.com/9BXFnxi.png


[-- Attachment #2: Type: text/html, Size: 558 bytes --]

Re: Nicer looking Info - Re: html manual +css

[Jean-Christophe Helary]

> On Jan 18, 2020, at 0:51, ndame <emacsuser@freemail.hu> wrote:
> 
> > I have eventually resumed "work" on this and here is what I got:
> > 
> > Original:
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/Visiting-Functions.html
> > 
> > Sample:
> > https://brandelune.github.io/code/Visiting-Functions.html
> 
> Don't you plan to apply similar changes to the built in Info?

No. I have no idea how to do that there.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: Nicer looking Info - html manual +css

[ndame]

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

> No. I have no idea how to do that there.

Normally it's only a matter of setting face colors, but I checked and
for some reason Info has only a few faces defined.

I wonder, for example, why Info has no face for Elisp code (or
generally, for code). Code examples are easier to read if they are
clearly separated visually from the main text like in the improved
HTML version. 
 

[-- Attachment #2: Type: text/html, Size: 451 bytes --]

Re: Nicer looking Info - html manual +css

[Stefan Kangas]

ndame <emacsuser@freemail.hu> writes:

> I wonder, for example, why Info has no face for Elisp code (or
> generally, for code). Code examples are easier to read if they are
> clearly separated visually from the main text like in the improved
> HTML version.

Even better if we could have proper syntax highlighting.

Best regards,
Stefan Kangas

Re: Nicer looking Info - html manual +css

[ndame]

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

 > Even better if we could have proper syntax highlighting.

Yes, that is the best, but first at least the code example markup in textinfo
should be converted to a face, because the markup is  already there, but left unused.

[-- Attachment #2: Type: text/html, Size: 256 bytes --]

Re: Nicer looking Info - html manual +css

[Eli Zaretskii]

> Date: Sun, 19 Jan 2020 06:04:00 +0000 (GMT)
> From: ndame <emacsuser@freemail.hu>
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> Yes, that is the best, but first at least the code example markup in textinfo
> should be converted to a face, because the markup is  already there, but left unused.

What is the markup to which you allude here?  Please elaborate,
because I don't think I understand what you mean.

Re: Nicer looking Info - html manual +css

[ndame]

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

> What is the markup to which you allude here? Please elaborate,
> because I don't think I understand what you mean.


I just checked the source and output files. Here's an example.


This an example code in the orignal texinfo file:


  In this example, point is between the @samp{a} and the @samp{c}.

  @example
  @group
  ---------- Buffer: foo ----------
  Gentlemen may cry ``Pea@point{}ce! Peace!,''
  but there is no peace.
  ---------- Buffer: foo ----------
  @end group
  @group
  (string (preceding-char))
       @result{} "a"
  (string (following-char))
       @result{} "c"
  @end group
  @end example



This is the HTML output and as you can see the example markup is kept
here in the form of a pre+class:


  <pre class="example">
       ---------- Buffer: foo ----------
       Gentlemen may cry ``Pea-!-ce! Peace!,''
       but there is no peace.
       ---------- Buffer: foo ----------

       (string (preceding-char))
            &rArr; "a"
       (string (following-char))
            &rArr; "c"
  </pre>



Here's the emacs info version, no trace of the example tag here:


  In this example, point is between the ‘a’ and the ‘c’.

       ---------- Buffer: foo ----------
       Gentlemen may cry ``Pea★ce! Peace!,''
       but there is no peace.
       ---------- Buffer: foo ----------

       (string (preceding-char))
            ⇒ "a"
       (string (following-char))
            ⇒ "c"




So if I'm not mistaken when the emacs info files are created, the
@example tag is dropped completely from the output. If this is the
case then it could be better to keep the @example tags in some form in
the emacs info output too and hide them with a face, for example. 

If the tag is kept then the source code examples in the info
documentation can get a face, so their appearance can be
customized. Without the tag it's not possible, because there is no
info in the file about where the code examples begin and end.
 

[-- Attachment #2: Type: text/html, Size: 3049 bytes --]

Re: Nicer looking Info - html manual +css

[Eli Zaretskii]

> Date: Sun, 19 Jan 2020 15:53:31 +0000 (GMT)
> From: ndame <emacsuser@freemail.hu>
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
> 	"stefan@marxist.se" <stefan@marxist.se>
> 
> So if I'm not mistaken when the emacs info files are created, the
> @example tag is dropped completely from the output.

Yes.

> If this is the
> case then it could be better to keep the @example tags in some form in
> the emacs info output too and hide them with a face, for example. 

If this is what you propose, then you should discuss this with the
Texinfo developers, not with Emacs developers.  We don't develop and
don't maintain the tools used to produce the Info manuals from their
Texinfo sources.  We just write the Texinfo sources and then invoke
the Texinfo processors to produce the Info format.

Re: Nicer looking Info - html manual +css

[Yuan Fu]

Since we are talking about Emacs’ Info, it would be nice to add proper variable pitch support. Right now if you enable variable-pitch-mode, there are two problems: 1) it still uses hard line breaks and doesn’t look nice 2) code are also turned into variable pitch.

Yuan

Re: Nicer looking Info - html manual +css

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Sun, 19 Jan 2020 12:27:22 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>,
>  "stefan@marxist.se" <stefan@marxist.se>,
>  "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> Since we are talking about Emacs’ Info, it would be nice to add proper variable pitch support.

You can't.  Info files are formatted by an external tool, and that
tool assumes a fixed-pitch font (and a text-mode display in general).

If you want a variable-pitch-mode manual, you should look at the HTML
output from Texinfo, not the Info output.

Re: Nicer looking Info - html manual +css

[ndame]

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

> If this is what you propose, then you should discuss this with the
> Texinfo developers, not with Emacs developers. We don't develop and
> don't maintain the tools used to produce the Info manuals from their
> Texinfo sources. We just write the Texinfo sources and then invoke
> the Texinfo processors to produce the Info format.

Thinking about this it occurred to me there is a simple heuristic
solution without involving the Texinfo folks.

Apparently @example is rendered after an empty line with a 5 spaces
indent. So it is easy to detect code sections, by looking for empty
lines followed by +5 spaces indented lines. The code section starts at
the empty line and ends when the indent is 5 spaces less again.

[-- Attachment #2: Type: text/html, Size: 816 bytes --]

Re: Nicer looking Info - html manual +css

[Eli Zaretskii]

> Date: Sun, 19 Jan 2020 18:48:34 +0000 (GMT)
> From: ndame <emacsuser@freemail.hu>
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>,
> 	"stefan@marxist.se" <stefan@marxist.se>
> 
> Thinking about this it occurred to me there is a simple heuristic
> solution without involving the Texinfo folks.
> 
> Apparently @example is rendered after an empty line with a 5 spaces
> indent. So it is easy to detect code sections, by looking for empty
> lines followed by +5 spaces indented lines. The code section starts at
> the empty line and ends when the indent is 5 spaces less again.

That won't work in general, because there are other kinds of markup
that end up indented like @example.

And even @example is not always indented exactly 5 spaces, because the
surrounding markup can affect that.  E.g., look at the code fragment
around line 127 of the "Time Conversion" node in the ELisp manual.

We cannot build a feature on such shaky foundations.  When 'makeinfo'
produces the Info output, the markup information is all but lost, and
nothing can bring it back.