html manual +css

html manual +css

[Jean-Christophe Helary]

The css file that's used for the web version of the HTML manuals is really nice. Especially in the Elisp Manual where the code is much more readable.

Is it OK to use the same (or a similar) file for the local HTML manuals?

Jean-Christophe

Re: html manual +css

[Paul Eggert]

On 06/02/2017 06:49 AM, Jean-Christophe Helary wrote:
> The css file that's used for the web version of the HTML manuals is really nice. Especially in the Elisp Manual where the code is much more readable.
>
> Is it OK to use the same (or a similar) file for the local HTML manuals?

I don't see why not. It is odd that the versions differ.

Re: html manual +css

[Jean-Christophe Helary]

> On Jun 2, 2017, at 23:28, Paul Eggert <eggert@cs.ucla.edu> wrote:
> 
> On 06/02/2017 06:49 AM, Jean-Christophe Helary wrote:
>> The css file that's used for the web version of the HTML manuals is really nice. Especially in the Elisp Manual where the code is much more readable.
>> 
>> Is it OK to use the same (or a similar) file for the local HTML manuals?
> 
> I don't see why not. It is odd that the versions differ.

Regarding the texi code, I'm seeing @smallexample and @example that are not relate to the actual size of the code but @smallexample as an HTML class is not associated with the brown background while @example is.

For ex. compare the code at the end of section 36.4 (@smallexample, 12 lines) to the code at the beginning of section 37.3 (@example, 3 lines).

So either we modify the CSS to add @smallexample as a class that receives the same background as @example (trivial and really fast), or we go through the whole texi file set and remove all instances of @smallexample (trivial too but longer)...

Jean-Christophe 

Re: html manual +css

[Jean-Christophe Helary]

> On Jun 2, 2017, at 23:45, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
> 
> So either we modify the CSS to add @smallexample as a class that receives the same background as @example (trivial and really fast), or we go through the whole texi file set and remove all instances of @smallexample (trivial too but longer)...

I mean *replace* all instances of @smallexample by @example.

> Jean-Christophe

Re: html manual +css

[Yuri Khan]

On Fri, Jun 2, 2017 at 9:45 PM, Jean-Christophe Helary
<jean.christophe.helary@gmail.com> wrote:

> Regarding the texi code, I'm seeing @smallexample and @example that are not relate to the actual size of the code but @smallexample as an HTML class is not associated with the brown background while @example is.

In the print version, @smallexample is set in a smaller font size so
that long lines fit. Paper has a ridiculously small line length limit.

Re: html manual +css

[Eli Zaretskii]

> From: Yuri Khan <yuri.v.khan@gmail.com>
> Date: Fri, 2 Jun 2017 22:14:57 +0700
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> On Fri, Jun 2, 2017 at 9:45 PM, Jean-Christophe Helary
> <jean.christophe.helary@gmail.com> wrote:
> 
> > Regarding the texi code, I'm seeing @smallexample and @example that are not relate to the actual size of the code but @smallexample as an HTML class is not associated with the brown background while @example is.
> 
> In the print version, @smallexample is set in a smaller font size so
> that long lines fit. Paper has a ridiculously small line length limit.

Right.  (Although the difference between the maximum line lengths in
these two is quite small.)  So you cannot simply replace all
@smallexample's by @example's, not without reviewing the line length
first.

Re: html manual +css

[Jean-Christophe Helary]

> On Jun 3, 2017, at 0:22, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>>> Regarding the texi code, I'm seeing @smallexample and @example that are not relate to the actual size of the code but @smallexample as an HTML class is not associated with the brown background while @example is.
>> 
>> In the print version, @smallexample is set in a smaller font size so
>> that long lines fit. Paper has a ridiculously small line length limit.
> 
> Right.  (Although the difference between the maximum line lengths in
> these two is quite small.)  So you cannot simply replace all
> @smallexample's by @example's, not without reviewing the line length
> first.

Ok, so I guess the easiest way to deal with that is to add the @smallexample class to the CSS then.

Jean-Christophe 

Re: html manual +css

[Jean-Christophe Helary]

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


> 2017/06/03 0:29、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
> 
>> 
>> On Jun 3, 2017, at 0:22, Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>>>> Regarding the texi code, I'm seeing @smallexample and @example that are not relate to the actual size of the code but @smallexample as an HTML class is not associated with the brown background while @example is.
>>> 
>>> In the print version, @smallexample is set in a smaller font size so
>>> that long lines fit. Paper has a ridiculously small line length limit.
>> 
>> Right.  (Although the difference between the maximum line lengths in
>> these two is quite small.)  So you cannot simply replace all
>> @smallexample's by @example's, not without reviewing the line length
>> first.
> 
> Ok, so I guess the easiest way to deal with that is to add the @smallexample class to the CSS then.

Ok, I have something that works, except that I need advice on the licences and on the whole process.

What I did to get the same CSS as the site is curl the css files. There are 3 of those:
https://www.gnu.org/software/emacs/manual.css
https://www.gnu.org/style.css
https://www.gnu.org/reset.css

To make things simpler I regrouped them into just one that I put the root of the /doc directory.

My understanding is that this file must have licence information, but it is composed of 3 different files, one of which (reset.css) has the following header:

/*
Copyright (c) 2009, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.net/yui/license.txt
version: 2.8.0r4
*/

So, what am I to do with the merged file ?

I modified the file so that smallexamples gets the same css as example.

Then, in each Makefile.in I modifier the HTML_OPTS to add the reference to the CSS data.
HTML_OPTS = --no-split --html --css-include=../manual.css

When I make the doc I get the CSS inside the <style> tag, as expected.

When that is properly implemented and committed, the best would be to have the gnu site change style.css so that both the online and the offline sets have the same looks.

Jean-Christophe


[-- Attachment #2: doc.html.diff --]
[-- Type: application/octet-stream, Size: 9921 bytes --]

diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in
index ffcc4baafd..cc751e5b6f 100644
--- a/doc/emacs/Makefile.in
+++ b/doc/emacs/Makefile.in
@@ -53,7 +53,7 @@ MKDIR_P = @MKDIR_P@
 
 GZIP_PROG = @GZIP_PROG@
 
-HTML_OPTS = --no-split --html
+HTML_OPTS = --no-split --html --css-include=../manual.css
 
 # Options used only when making info output.
 # --no-split is only needed because of MS-DOS.
diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in
index d8e203fd06..34e5422111 100644
--- a/doc/lispintro/Makefile.in
+++ b/doc/lispintro/Makefile.in
@@ -41,7 +41,7 @@ MKDIR_P = @MKDIR_P@
 
 GZIP_PROG = @GZIP_PROG@
 
-HTML_OPTS = --no-split --html
+HTML_OPTS = --no-split --html --css-include=../manual.css
 
 # Options used only when making info output.
 INFO_OPTS= --no-split
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 89eb81093d..2cb36c038c 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -45,7 +45,7 @@ MKDIR_P = @MKDIR_P@
 
 GZIP_PROG = @GZIP_PROG@
 
-HTML_OPTS = --no-split --html
+HTML_OPTS = --no-split --html --css-include=../manual.css
 
 # Options used only when making info output.
 INFO_OPTS= --no-split
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index f365c80493..e80e778bec 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -965,10 +965,9 @@ extra values to be formatted are ignored.
 decimal number immediately after the initial @samp{%}, followed by a
 literal dollar sign @samp{$}.  It causes the format specification to
 convert the argument with the given number instead of the next
-argument.  Field numbers start at 1.  A field number should differ
-from the other field numbers in the same format.  A format can contain
-either numbered or unnumbered format specifications but not both,
-except that @samp{%%} can be mixed with numbered specifications.
+argument.  Field numbers start at 1.  A format can contain either
+numbered or unnumbered format specifications but not both, except that
+@samp{%%} can be mixed with numbered specifications.
 
 @example
 (format "%2$s, %3$s, %%, %1$s" "x" "y" "z")
diff --git a/doc/manual.css b/doc/manual.css
new file mode 100644
index 0000000000..0aec934601
--- /dev/null
+++ b/doc/manual.css
@@ -0,0 +1,193 @@
+/*
+Copyright (c) 2009, Yahoo! Inc. All rights reserved.
+Code licensed under the BSD License:
+http://developer.yahoo.net/yui/license.txt
+version: 2.8.0r4
+*/
+html{color:#000;background:#FFF;}body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td{margin:0;padding:0;}table{border-collapse:collapse;border-spacing:0;}fieldset,img{border:0;}address,caption,cite,code,dfn,em,strong,th,var,optgroup{font-style:inherit;font-weight:inherit;}del,ins{text-decoration:none;}li{list-style:none;}caption,th{text-align:left;}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal;}q:before,q:after{content:'';}abbr,acronym{border:0;font-variant:normal;}sup{vertical-align:baseline;}sub{vertical-align:baseline;}legend{color:#000;}input,button,textarea,select,optgroup,option{font-family:inherit;font-size:inherit;font-style:inherit;font-weight:inherit;}input,button,textarea,select{*font-size:100%;}
+
+/***  PAGE LAYOUT  ***/
+
+html, body {
+   font-size: 1em;
+   text-align: left;
+   text-decoration: none;
+}
+html { background-color: #e7e7e7; }
+
+body {
+   max-width: 74.92em;
+   margin: 0 auto;
+   padding: .5em 1em 1em 1em;
+   background-color: white;
+   border: .1em solid #c0c0c0;
+}
+
+
+/*** BASIC ELEMENTS ***/
+
+/* Size and positioning */
+
+p, pre, li, dt, dd, table, code, address { line-height: 1.3em; }
+
+h1 { font-size: 2em; margin: 1em 0 }
+h2 { font-size: 1.50em; margin: 1.0em 0 0.87em 0; }
+h3 { font-size: 1.30em; margin: 1.0em 0 0.87em 0; }
+h4 { font-size: 1.13em; margin: 1.0em 0 0.88em 0; }
+h5 { font-size: 1.00em; margin: 1.0em 0 1.00em 0; }
+
+p, pre { margin: 1em 0; }
+pre { overflow: auto; padding-bottom: .3em; }
+
+ul, ol, blockquote { margin-left: 1.5%; margin-right: 1.5%; }
+hr { margin: 1em 0; }
+/* Lists of underlined links are difficult to read. The top margin
+   gives a little more spacing between entries. */
+ul li { margin: .5em 1em; }
+ol li { margin: 1em; }
+ol ul li { margin: .5em 1em; }
+ul li p, ul ul li { margin-top: .3em; margin-bottom: .3em; }
+ul ul, ol ul { margin-top: 0; margin-bottom: 0; }
+
+/* Separate description lists from preceding text */
+dl { margin: 1em 0 0 0; }
+/* separate the "term" from subsequent "description" */
+dt { margin: .5em 0; }
+/* separate the "description" from subsequent list item
+   when the final <dd> child is an anonymous box */
+dd { margin: .5em 3% 1em 3%; }
+/* separate anonymous box (used to be the first element in <dd>)
+   from subsequent <p> */
+dd p { margin: .5em 0; }
+
+table {
+   display: block; overflow: auto;
+   margin-top: 1.5em; margin-bottom: 1.5em;
+}
+th { padding: .3em .5em; text-align: center; }
+td { padding: .2em .5em; }
+
+address { margin-bottom: 1em; }
+caption { margin-bottom: .5em; text-align: center; }
+sup { vertical-align: super; }
+sub { vertical-align: sub; }
+
+/* Style */
+
+h1, h2, h3, h4, h5, h6, strong, dt, th { font-weight: bold; }
+
+/* The default color (black) is too dark for large text in
+   bold font. */
+h1, h2, h3, h4 { color: #333; }
+h5, h6, dt { color: #222; }
+
+a[href] { color: #005090; }
+a[href]:visited { color: #100070; }
+a[href]:active, a[href]:hover {
+   color: #100070;
+   text-decoration: none;
+}
+
+h1 a[href]:visited, h2 a[href]:visited, h3 a[href]:visited,
+ h4 a[href]:visited { color: #005090; }
+h1 a[href]:hover, h2 a[href]:hover, h3 a[href]:hover,
+ h4 a[href]:hover { color: #100070; }
+
+ol { list-style: decimal outside;}
+ul { list-style: square outside; }
+ul ul, ol ul { list-style: circle; }
+li { list-style: inherit; }
+
+hr { background-color: #ede6d5; }
+table { border: 0; }
+
+abbr,acronym {
+   border-bottom:1px dotted #000;
+   text-decoration: none;
+   cursor:help;
+}
+del { text-decoration: line-through; }
+em { font-style: italic; }
+small { font-size: .9em; }
+
+img { max-width: 100%}
+
+
+/*** SIMPLE CLASSES ***/
+
+.center, .c { text-align: center; }
+.nocenter{ text-align: left; }
+
+.underline { text-decoration: underline; }
+.nounderline { text-decoration: none; }
+
+.no-bullet { list-style: none; }
+.inline-list li { display: inline }
+
+.netscape4, .no-display { display: none; }
+
+
+/*** MANUAL PAGES ***/
+
+/* This makes the very long tables of contents in Gnulib and other
+   manuals easier to read. */
+.contents ul, .shortcontents ul { font-weight: bold; }
+.contents ul ul, .shortcontents ul ul { font-weight: normal; }
+.contents ul { list-style: none; }
+
+/* For colored navigation bars (Emacs manual): make the bar extend
+   across the whole width of the page and give it a decent height. */
+.header, .node { margin: 0 -1em; padding: 0 1em; }
+.header p, .node p { line-height: 2em; }
+
+/* For navigation links */
+.node a, .header a { display: inline-block; line-height: 2em; }
+.node a:hover, .header a:hover { background: #f2efe4; }
+
+/* Inserts */
+table.cartouche td { padding: 1.5em; }
+
+div.display, div.lisp, div.smalldisplay,
+ div.smalllisp { margin-left: 3%; }
+
+div.example, div.smallexample { padding: .8em 1.2em .4em; }
+pre.example { padding: .8em 1.2em; }
+div.example, div.smallexample, pre.smallexample, pre.example {
+   margin: 1em 0 1em 3% ;
+   -webkit-border-radius: .3em;
+   -moz-border-radius: .3em;
+   border-radius: .3em;
+   border: 1px solid #d4cbb6;
+   background-color: #f2efe4;
+}
+div.example > pre.example {
+   padding: 0 0 .4em;
+   margin: 0;
+   border: none;
+}
+
+pre.menu-comment { padding-top: 1.3em; margin: 0; }
+
+
+/*** FOR WIDE SCREENS ***/
+
+@media (min-width: 40em) {
+   body { padding: .5em 3em 1em 3em; }
+   div.header, div.node { margin: 0 -3em; padding: 0 3em; }
+}
+
+/* Style-sheet to use for Emacs manuals  */
+
+
+/* makeinfo convert @deffn and similar functions to something inside
+   <blockquote>.  style.css uses italic for blockquote.  This looks poor
+   in the Emacs manuals, which make extensive use of @defun (etc).
+   In particular, references to function arguments appear as <var>
+   inside <blockquote>.  Since <var> is also italic, it makes it
+   impossible to distinguish variables.  We could change <var> to
+   e.g. bold-italic, or normal, or a different color, but that does
+   not look as good IMO.  So we just override blockquote to be non-italic.
+   */
+blockquote { font-style: normal; }
+
+var { font-style: italic; }
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
index 8ff823200a..b8e0e857bd 100644
--- a/doc/misc/Makefile.in
+++ b/doc/misc/Makefile.in
@@ -46,7 +46,7 @@ MKDIR_P = @MKDIR_P@
 
 GZIP_PROG = @GZIP_PROG@
 
-HTML_OPTS = --no-split --html
+HTML_OPTS = --no-split --html --css-include=../manual.css
 
 # Options used only when making info output.
 # (Note that idlwave, info used --nosplit even without the .info extension.)
diff --git a/src/editfns.c b/src/editfns.c
index a5088b0a1f..29af25aab4 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -3901,10 +3901,9 @@ where field is [0-9]+ followed by a literal dollar "$", flags is
 followed by [0-9]+.
 
 If a %-sequence is numbered with a field with positive value N, the
-Nth argument is substituted instead of the next one.  A field number
-should differ from the other field numbers in the same format.  A
-format can contain either numbered or unnumbered %-sequences but not
-both, except that %% can be mixed with numbered %-sequences.
+Nth argument is substituted instead of the next one.  A format can
+contain either numbered or unnumbered %-sequences but not both, except
+that %% can be mixed with numbered %-sequences.
 
 The + flag character inserts a + before any positive number, while a
 space inserts a space before any positive number; these flags only

Re: html manual +css

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > What I did to get the same CSS as the site is curl the css files. There are 3 of those:
  > https://www.gnu.org/software/emacs/manual.css
  > https://www.gnu.org/style.css
  > https://www.gnu.org/reset.css

Each of these files has a licensing problem.  I asked FSF staff to fix
the last two, and mailed to emacs-devel about the first.

In the meantime, please don't copy any of that code, with or without changes,
to any other file that will be distributed to the public.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: html manual +css

[Jean-Christophe Helary]

> 2017/06/07 7:41、Richard Stallman <rms@gnu.org>のメール:
> 
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>> https://www.gnu.org/software/emacs/manual.css
>> https://www.gnu.org/style.css
>> https://www.gnu.org/reset.css
> 
> Each of these files has a licensing problem.  I asked FSF staff to fix
> the last two, and mailed to emacs-devel about the first.
> 
> In the meantime, please don't copy any of that code, with or without changes,
> to any other file that will be distributed to the public.

CSS is not high level wizardry, maybe it would be simpler to create a new set of rules for the offline manual ?

Jean-Christophe 

Re: html manual +css

[Jean-Christophe Helary]

> Jun 7, 2017 8:47、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
> 
>>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>>> https://www.gnu.org/software/emacs/manual.css
>>> https://www.gnu.org/style.css
>>> https://www.gnu.org/reset.css
>> 
>> Each of these files has a licensing problem.  I asked FSF staff to fix
>> the last two, and mailed to emacs-devel about the first.
>> 
>> In the meantime, please don't copy any of that code, with or without changes,
>> to any other file that will be distributed to the public.
> 
> CSS is not high level wizardry, maybe it would be simpler to create a new set of rules for the offline manual ?

I've created a single css file which renders in a way that's similar to the web version of the HTML pages (it is not identical though).

I'd like to know what kind of licence should such a CSS file come with.

Jean-Christophe

Re: html manual +css

[Jean-Christophe Helary]

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

The css I wrote:
https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css

It is something I had done a while ago so I just spent a few hours today cleaning it up but I'm really not sure how I came up with the various values anymore :)

Anyway, if it looks useful I'd like to think of ways to have it more widely used.

Also, there are plenty of things that would be nice to have but in a way we're hitting the limits of the texinfo output (and my css skills too, of course).

For ex:

@deffn Command find-file filename &optional wildcards

becomes

<dt id="index-find_002dfile">Command: <strong>find-file</strong> <em>filename &amp;optional wildcards</em></dt>

it would be nice to have the arguments tagged individually and the &optional or &rest keywords tagged in a different way. Also to have the various templates identified for what they are. Maybe something like:

<dt id="index-find_002dfile" class="command">Command: <strong class="command-name">find-file</strong> <em class="argument">filename</em> <span class="keyword">&amp;optional</span> <em class="optional">wildcards</em></dt>

Also, examples should have similar tagging:

@smallexample
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
@end smallexample

could be something like 

@smallexample
(@commandname switch-to-buffer (@commandname find-file-noselect @arguments filename nil nil wildcards))
@end smallexample

so that we can have ways to target their contents with css.

Jean-Christophe 

> On Jun 7, 2017, at 23:27, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
> 
> 
>> Jun 7, 2017 8:47、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
>> 
>>>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>>>> https://www.gnu.org/software/emacs/manual.css
>>>> https://www.gnu.org/style.css
>>>> https://www.gnu.org/reset.css
>>> 
>>> Each of these files has a licensing problem.  I asked FSF staff to fix
>>> the last two, and mailed to emacs-devel about the first.
>>> 
>>> In the meantime, please don't copy any of that code, with or without changes,
>>> to any other file that will be distributed to the public.
>> 
>> CSS is not high level wizardry, maybe it would be simpler to create a new set of rules for the offline manual ?
> 
> I've created a single css file which renders in a way that's similar to the web version of the HTML pages (it is not identical though).
> 
> I'd like to know what kind of licence should such a CSS file come with.
> 
> Jean-Christophe

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

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 24, 2019, at 2:20, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> Sample:
>> https://brandelune.github.io/code/Visiting-Functions.html
> 
> Thanks, this looks pretty good on my desktop (haven't tried it
> elsewhere yet).  One thing I'd find useful is to keep the next/up first
> line "floating at the top", so they're always available without having
> to scroll to the top or to the bottom.
> [ Tho I guess when reading on a small screen I might prefer it the way
> it is now.  ]

Thank you for the comment.

That should not be difficult, I'll try to do something later this evening.

JC

> 
> 
>        Stefan
> 
> 
>> The css I wrote:
>> https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css
>> 
>> It is something I had done a while ago so I just spent a few hours today
>> cleaning it up but I'm really not sure how I came up with the various values
>> anymore :)
>> 
>> Anyway, if it looks useful I'd like to think of ways to have it more widely used.
>> 
>> Also, there are plenty of things that would be nice to have but in a way
>> we're hitting the limits of the texinfo output (and my css skills too, of
>> course).
>> 
>> For ex:
>> 
>> @deffn Command find-file filename &optional wildcards
>> 
>> becomes
>> 
>> <dt id="index-find_002dfile">Command: <strong>find-file</strong>
>> <em>filename &amp;optional wildcards</em></dt>
>> 
>> it would be nice to have the arguments tagged individually and the &optional
>> or &rest keywords tagged in a different way. Also to have the various
>> templates identified for what they are. Maybe something like:
>> 
>> <dt id="index-find_002dfile" class="command">Command: <strong
>> class="command-name">find-file</strong> <em class="argument">filename</em>
>> <span class="keyword">&amp;optional</span> <em
>> class="optional">wildcards</em></dt>
>> 
>> Also, examples should have similar tagging:
>> 
>> @smallexample
>> (switch-to-buffer (find-file-noselect filename nil nil wildcards))
>> @end smallexample
>> 
>> could be something like 
>> 
>> @smallexample
>> (@commandname switch-to-buffer (@commandname find-file-noselect @arguments
>> filename nil nil wildcards))
>> @end smallexample
>> 
>> so that we can have ways to target their contents with css.
>> 
>> Jean-Christophe 
>> 
>>> On Jun 7, 2017, at 23:27, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
>>> 
>>> 
>>>> Jun 7, 2017 8:47、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
>>>> 
>>>>>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>>>>>> https://www.gnu.org/software/emacs/manual.css
>>>>>> https://www.gnu.org/style.css
>>>>>> https://www.gnu.org/reset.css
>>>>> 
>>>>> Each of these files has a licensing problem.  I asked FSF staff to fix
>>>>> the last two, and mailed to emacs-devel about the first.
>>>>> 
>>>>> In the meantime, please don't copy any of that code, with or without changes,
>>>>> to any other file that will be distributed to the public.
>>>> 
>>>> CSS is not high level wizardry, maybe it would be simpler to create a new
>>>> set of rules for the offline manual ?
>>> 
>>> I've created a single css file which renders in a way that's similar to
>>> the web version of the HTML pages (it is not identical though).
>>> 
>>> I'd like to know what kind of licence should such a CSS file come with.
>>> 
>>> Jean-Christophe
>> 
>> Jean-Christophe Helary
>> -----------------------------------------------
>> http://mac4translators.blogspot.com @brandelune

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 24, 2019, at 2:20, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> Sample:
>> https://brandelune.github.io/code/Visiting-Functions.html
> 
> Thanks, this looks pretty good on my desktop (haven't tried it
> elsewhere yet).  One thing I'd find useful is to keep the next/up first
> line "floating at the top", so they're always available without having
> to scroll to the top or to the bottom.
> [ Tho I guess when reading on a small screen I might prefer it the way
> it is now.  ]

Ok, so I have something that works both ways:

1) when the display is wide enough to have the full horizontal menu, the menu is displayed horizontally and follows the scrolling.

2) when the display is not wide enough to have the full horizontal menu, the menu is displayed on the right side of the screen, as a list of links, with "icons" before the link names to hint at their use, and the menu sticks to its original position.

All that is implemented without modifying the HTML output by texinfo. I'm just using the existing HTML tags and attributes to "anchor" CSS variations on them.

Would you mind checking if that works as you intended ?

Jean-Christophe

> 
> 
>        Stefan
> 
> 
>> The css I wrote:
>> https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css
>> 
>> It is something I had done a while ago so I just spent a few hours today
>> cleaning it up but I'm really not sure how I came up with the various values
>> anymore :)
>> 
>> Anyway, if it looks useful I'd like to think of ways to have it more widely used.
>> 
>> Also, there are plenty of things that would be nice to have but in a way
>> we're hitting the limits of the texinfo output (and my css skills too, of
>> course).
>> 
>> For ex:
>> 
>> @deffn Command find-file filename &optional wildcards
>> 
>> becomes
>> 
>> <dt id="index-find_002dfile">Command: <strong>find-file</strong>
>> <em>filename &amp;optional wildcards</em></dt>
>> 
>> it would be nice to have the arguments tagged individually and the &optional
>> or &rest keywords tagged in a different way. Also to have the various
>> templates identified for what they are. Maybe something like:
>> 
>> <dt id="index-find_002dfile" class="command">Command: <strong
>> class="command-name">find-file</strong> <em class="argument">filename</em>
>> <span class="keyword">&amp;optional</span> <em
>> class="optional">wildcards</em></dt>
>> 
>> Also, examples should have similar tagging:
>> 
>> @smallexample
>> (switch-to-buffer (find-file-noselect filename nil nil wildcards))
>> @end smallexample
>> 
>> could be something like 
>> 
>> @smallexample
>> (@commandname switch-to-buffer (@commandname find-file-noselect @arguments
>> filename nil nil wildcards))
>> @end smallexample
>> 
>> so that we can have ways to target their contents with css.
>> 
>> Jean-Christophe 
>> 
>>> On Jun 7, 2017, at 23:27, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
>>> 
>>> 
>>>> Jun 7, 2017 8:47、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
>>>> 
>>>>>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>>>>>> https://www.gnu.org/software/emacs/manual.css
>>>>>> https://www.gnu.org/style.css
>>>>>> https://www.gnu.org/reset.css
>>>>> 
>>>>> Each of these files has a licensing problem.  I asked FSF staff to fix
>>>>> the last two, and mailed to emacs-devel about the first.
>>>>> 
>>>>> In the meantime, please don't copy any of that code, with or without changes,
>>>>> to any other file that will be distributed to the public.
>>>> 
>>>> CSS is not high level wizardry, maybe it would be simpler to create a new
>>>> set of rules for the offline manual ?
>>> 
>>> I've created a single css file which renders in a way that's similar to
>>> the web version of the HTML pages (it is not identical though).
>>> 
>>> I'd like to know what kind of licence should such a CSS file come with.
>>> 
>>> Jean-Christophe
>> 
>> Jean-Christophe Helary
>> -----------------------------------------------
>> http://mac4translators.blogspot.com @brandelune

Re: html manual +css

[Jean-Christophe Helary]

> 2) when the display is not wide enough to have the full horizontal menu, the menu is displayed on the right side of the screen, 

I meant "left side".

JC

> On Dec 24, 2019, at 23:37, Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> wrote:
> 
> 
> 
>> On Dec 24, 2019, at 2:20, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> 
>>> Sample:
>>> https://brandelune.github.io/code/Visiting-Functions.html
>> 
>> Thanks, this looks pretty good on my desktop (haven't tried it
>> elsewhere yet).  One thing I'd find useful is to keep the next/up first
>> line "floating at the top", so they're always available without having
>> to scroll to the top or to the bottom.
>> [ Tho I guess when reading on a small screen I might prefer it the way
>> it is now.  ]
> 
> Ok, so I have something that works both ways:
> 
> 1) when the display is wide enough to have the full horizontal menu, the menu is displayed horizontally and follows the scrolling.
> 
> 2) when the display is not wide enough to have the full horizontal menu, the menu is displayed on the right side of the screen, as a list of links, with "icons" before the link names to hint at their use, and the menu sticks to its original position.
> 
> All that is implemented without modifying the HTML output by texinfo. I'm just using the existing HTML tags and attributes to "anchor" CSS variations on them.
> 
> Would you mind checking if that works as you intended ?
> 
> Jean-Christophe
> 
>> 
>> 
>>       Stefan
>> 
>> 
>>> The css I wrote:
>>> https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css
>>> 
>>> It is something I had done a while ago so I just spent a few hours today
>>> cleaning it up but I'm really not sure how I came up with the various values
>>> anymore :)
>>> 
>>> Anyway, if it looks useful I'd like to think of ways to have it more widely used.
>>> 
>>> Also, there are plenty of things that would be nice to have but in a way
>>> we're hitting the limits of the texinfo output (and my css skills too, of
>>> course).
>>> 
>>> For ex:
>>> 
>>> @deffn Command find-file filename &optional wildcards
>>> 
>>> becomes
>>> 
>>> <dt id="index-find_002dfile">Command: <strong>find-file</strong>
>>> <em>filename &amp;optional wildcards</em></dt>
>>> 
>>> it would be nice to have the arguments tagged individually and the &optional
>>> or &rest keywords tagged in a different way. Also to have the various
>>> templates identified for what they are. Maybe something like:
>>> 
>>> <dt id="index-find_002dfile" class="command">Command: <strong
>>> class="command-name">find-file</strong> <em class="argument">filename</em>
>>> <span class="keyword">&amp;optional</span> <em
>>> class="optional">wildcards</em></dt>
>>> 
>>> Also, examples should have similar tagging:
>>> 
>>> @smallexample
>>> (switch-to-buffer (find-file-noselect filename nil nil wildcards))
>>> @end smallexample
>>> 
>>> could be something like 
>>> 
>>> @smallexample
>>> (@commandname switch-to-buffer (@commandname find-file-noselect @arguments
>>> filename nil nil wildcards))
>>> @end smallexample
>>> 
>>> so that we can have ways to target their contents with css.
>>> 
>>> Jean-Christophe 
>>> 
>>>> On Jun 7, 2017, at 23:27, Jean-Christophe Helary <jean.christophe.helary@gmail.com> wrote:
>>>> 
>>>> 
>>>>> Jun 7, 2017 8:47、Jean-Christophe Helary <jean.christophe.helary@gmail.com>のメール:
>>>>> 
>>>>>>> What I did to get the same CSS as the site is curl the css files. There are 3 of those:
>>>>>>> https://www.gnu.org/software/emacs/manual.css
>>>>>>> https://www.gnu.org/style.css
>>>>>>> https://www.gnu.org/reset.css
>>>>>> 
>>>>>> Each of these files has a licensing problem.  I asked FSF staff to fix
>>>>>> the last two, and mailed to emacs-devel about the first.
>>>>>> 
>>>>>> In the meantime, please don't copy any of that code, with or without changes,
>>>>>> to any other file that will be distributed to the public.
>>>>> 
>>>>> CSS is not high level wizardry, maybe it would be simpler to create a new
>>>>> set of rules for the offline manual ?
>>>> 
>>>> I've created a single css file which renders in a way that's similar to
>>>> the web version of the HTML pages (it is not identical though).
>>>> 
>>>> I'd like to know what kind of licence should such a CSS file come with.
>>>> 
>>>> Jean-Christophe
>>> 
>>> Jean-Christophe Helary
>>> -----------------------------------------------
>>> http://mac4translators.blogspot.com @brandelune

Re: html manual +css

[Stefan Monnier]

> Ok, so I have something that works both ways:
>
> 1) when the display is wide enough to have the full horizontal menu, the
> menu is displayed horizontally and follows the scrolling.
>
> 2) when the display is not wide enough to have the full horizontal menu, the
> menu is displayed on the right side of the screen, as a list of links, with
> "icons" before the link names to hint at their use, and the menu sticks to
> its original position.

Looks great on my desktop, thanks,

> Would you mind checking if that works as you intended ?

It does.  I just now tried to look at the page from a phone and it looks
identical, which I guess is good (indeed in pixels, my desktop's browser
and my phone's browser (when the phone is in portrait position) have
about the same number of pixels), but it makes the site difficult to
read on my phone (I have to zoom on the various parts to read them ;-)
It's definitely no worse than what we currently have on gnu.org, tho!

It's more readable when I put my phone in landscape, but then this first
line menu ends up using a large fraction of my screen real estate so
I wouldn't want it to always stay on-screen.
[ I guess this is the only part which I could consider a regression
  compared to what we currently have on gnu.org.  And it's a result of
  what I asked for (and like) when reading on a desktop.  Oh well!  ]

To clarify: it's never occurred to me to look at such docs on my phone,
so it's probably not an important use case.


        Stefan "whose phone's browser has more pixels than his desktop's"

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 26, 2019, at 7:03, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> Ok, so I have something that works both ways:
>> 
>> 1) when the display is wide enough to have the full horizontal menu, the
>> menu is displayed horizontally and follows the scrolling.
>> 
>> 2) when the display is not wide enough to have the full horizontal menu, the
>> menu is displayed on the right side of the screen, as a list of links, with
>> "icons" before the link names to hint at their use, and the menu sticks to
>> its original position.
> 
> Looks great on my desktop, thanks,
> 
>> Would you mind checking if that works as you intended ?
> 
> It does.  I just now tried to look at the page from a phone and it looks
> identical,

Well that was not intended. The result was good when looking at the page from a "phone" developer mode in Firefox/Safari but on a real phone it was not the intended result.

You can see what I intended to do by reducing the width of your desktop browser window until you see the modification.

> which I guess is good (indeed in pixels, my desktop's browser
> and my phone's browser (when the phone is in portrait position) have
> about the same number of pixels), but it makes the site difficult to
> read on my phone (I have to zoom on the various parts to read them ;-)
> It's definitely no worse than what we currently have on gnu.org, tho!

Indeed.

> It's more readable when I put my phone in landscape, but then this first
> line menu ends up using a large fraction of my screen real estate so
> I wouldn't want it to always stay on-screen.

:) And that's what I tried to avoid.

> [ I guess this is the only part which I could consider a regression
>  compared to what we currently have on gnu.org.  And it's a result of
>  what I asked for (and like) when reading on a desktop.  Oh well!  ]

But that is something we can achieve. I'm just brushing up the CSS skills that I had 20 years ago and the technology has evolved a huge lot to answer the needs of mobile browsers. Maybe you've heard the term already, it is called "responsive design" and it aims at making a page flow better when the form is constrained by smaller displays.

> To clarify: it's never occurred to me to look at such docs on my phone,
> so it's probably not an important use case.

No, it is. Especially when you want to *read* the manual/reference.

I'll get back to the list with a useable proposal. Sorry for the noise.

>        Stefan "whose phone's browser has more pixels than his desktop's"

Same here. It's my first mobile phone in about 10 years. I'm shocked at how fast things have changed. Although I was just thinking that the maximum 1kb offset of the charset declaration from the beginning of an HTML file is the same amount of useable memory my ZX81 had when I bought it about 40 years ago...

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

Re: html manual +css

[Jean-Christophe Helary]

Stefan,

Ok, I've done it :)

1) to have mobile browsers recognize media queries related to the display size it is necessary to add a <meta> tag to the <head> that contains a reference to the "viewport" of the display:

https://www.reddit.com/r/css/comments/eft71n/iphone_safari_does_not_respond_to_maxwidth_media/

2) to add that to the texinfo output I had to tweak the makefile like this:

HTML_OPTS = --html --css-ref=emacs.css -c EXTRA_HEAD="<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">"

3) then I put all that online and now the sample that I presented yesterday works perfectly well on a small mobile device, as you wanted.

The modification I added to the CSS for displays that have a maximum width of 40 ems is visible in the @media part:

https://brandelune.github.io/code/emacs.css

Anyway, here are the links again:

Original:
https://www.gnu.org/software/emacs/manual/html_node/elisp/Visiting-Functions.html

Sample:
https://brandelune.github.io/code/Visiting-Functions.html

It should look tremendously better on small displays now, and I'm sure there is ample room for improvements (add different break points to target different displays) but that sample should be enough to get the ball rolling, hopefully somewhere :)

Let me know what you think.

JC


> On Dec 26, 2019, at 9:08, Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> wrote:
> 
> 
> 
>> On Dec 26, 2019, at 7:03, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> 
>>> Ok, so I have something that works both ways:
>>> 
>>> 1) when the display is wide enough to have the full horizontal menu, the
>>> menu is displayed horizontally and follows the scrolling.
>>> 
>>> 2) when the display is not wide enough to have the full horizontal menu, the
>>> menu is displayed on the right side of the screen, as a list of links, with
>>> "icons" before the link names to hint at their use, and the menu sticks to
>>> its original position.
>> 
>> Looks great on my desktop, thanks,
>> 
>>> Would you mind checking if that works as you intended ?
>> 
>> It does.  I just now tried to look at the page from a phone and it looks
>> identical,
> 
> Well that was not intended. The result was good when looking at the page from a "phone" developer mode in Firefox/Safari but on a real phone it was not the intended result.
> 
> You can see what I intended to do by reducing the width of your desktop browser window until you see the modification.
> 
>> which I guess is good (indeed in pixels, my desktop's browser
>> and my phone's browser (when the phone is in portrait position) have
>> about the same number of pixels), but it makes the site difficult to
>> read on my phone (I have to zoom on the various parts to read them ;-)
>> It's definitely no worse than what we currently have on gnu.org, tho!
> 
> Indeed.
> 
>> It's more readable when I put my phone in landscape, but then this first
>> line menu ends up using a large fraction of my screen real estate so
>> I wouldn't want it to always stay on-screen.
> 
> :) And that's what I tried to avoid.
> 
>> [ I guess this is the only part which I could consider a regression
>> compared to what we currently have on gnu.org.  And it's a result of
>> what I asked for (and like) when reading on a desktop.  Oh well!  ]
> 
> But that is something we can achieve. I'm just brushing up the CSS skills that I had 20 years ago and the technology has evolved a huge lot to answer the needs of mobile browsers. Maybe you've heard the term already, it is called "responsive design" and it aims at making a page flow better when the form is constrained by smaller displays.
> 
>> To clarify: it's never occurred to me to look at such docs on my phone,
>> so it's probably not an important use case.
> 
> No, it is. Especially when you want to *read* the manual/reference.
> 
> I'll get back to the list with a useable proposal. Sorry for the noise.
> 
>>       Stefan "whose phone's browser has more pixels than his desktop's"
> 
> Same here. It's my first mobile phone in about 10 years. I'm shocked at how fast things have changed. Although I was just thinking that the maximum 1kb offset of the charset declaration from the beginning of an HTML file is the same amount of useable memory my ZX81 had when I bought it about 40 years ago...
> 
> Jean-Christophe Helary
> -----------------------------------------------
> http://mac4translators.blogspot.com @brandelune

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

Re: html manual +css

[Stefan Monnier]

> 1) to have mobile browsers recognize media queries related to the display
> size it is necessary to add a <meta> tag to the <head> that contains
> a reference to the "viewport" of the display:
>
> https://www.reddit.com/r/css/comments/eft71n/iphone_safari_does_not_respond_to_maxwidth_media/

I wonder why the HTML needs this and what it really means.
[ E.g. the name "device-width" makes it sound like it intends to reflect
  the physical size of the screen, whereas people watch their phone
  screen from a much shorter distance than their desktop screen, so we
  should pay attention to the "apparent size" rather than the physical
  size.  ]

> 3) then I put all that online and now the sample that I presented yesterday
> works perfectly well on a small mobile device, as you wanted.

Portrait mode now looks great, indeed, thanks.

In landscape mode, tho, the browser is wide enough that the top-header
fits on a single line and hence "sticks around" when you scroll, thus
eating up a lot of screen real estate (especially since phones nowadays
have an appalling aspect ratio, very far from the beloved 4:3).


        Stefan

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 26, 2019, at 23:45, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> 1) to have mobile browsers recognize media queries related to the display
>> size it is necessary to add a <meta> tag to the <head> that contains
>> a reference to the "viewport" of the display:
>> 
>> https://www.reddit.com/r/css/comments/eft71n/iphone_safari_does_not_respond_to_maxwidth_media/
> 
> I wonder why the HTML needs this and what it really means.
> [ E.g. the name "device-width" makes it sound like it intends to reflect
>  the physical size of the screen, whereas people watch their phone
>  screen from a much shorter distance than their desktop screen, so we
>  should pay attention to the "apparent size" rather than the physical
>  size.  ]

The MDN doc on viewport is here:
https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag

The W3C is trying to port that directly to CSS but the spec is only a draft:
https://drafts.csswg.org/css-device-adapt/#the-viewport

My understanding is that as you noticed, pixel numbers on mobile are equivalent or superior to desk/laptops but pixel density is much higher on mobile, so there is a need to tell the browser not to consider how many pixels are required to display a given content but on which viewport is actually is displayed.

https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b

and

https://www.quirksmode.org/mobile/viewports2.html

I still need to wrap my mind around all that but it will make sense eventually :) I'm going to spend a few days reading all that and practicing...

>> 3) then I put all that online and now the sample that I presented yesterday
>> works perfectly well on a small mobile device, as you wanted.
> 
> Portrait mode now looks great, indeed, thanks.
> 
> In landscape mode, tho, the browser is wide enough that the top-header
> fits on a single line and hence "sticks around" when you scroll, thus
> eating up a lot of screen real estate (especially since phones nowadays
> have an appalling aspect ratio, very far from the beloved 4:3).

Ooops. Ok, I'm working on that...


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

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 27, 2019, at 0:08, Jean-Christophe Helary <jean.christophe.helary@traduction-libre.org> wrote:
> 
> 
> 
>> On Dec 26, 2019, at 23:45, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>> 
>>> 1) to have mobile browsers recognize media queries related to the display
>>> size it is necessary to add a <meta> tag to the <head> that contains
>>> a reference to the "viewport" of the display:
>>> 
>>> https://www.reddit.com/r/css/comments/eft71n/iphone_safari_does_not_respond_to_maxwidth_media/
>> 
>> I wonder why the HTML needs this and what it really means.
>> [ E.g. the name "device-width" makes it sound like it intends to reflect
>> the physical size of the screen, whereas people watch their phone
>> screen from a much shorter distance than their desktop screen, so we
>> should pay attention to the "apparent size" rather than the physical
>> size.  ]
> 
> The MDN doc on viewport is here:
> https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag
> 
> The W3C is trying to port that directly to CSS but the spec is only a draft:
> https://drafts.csswg.org/css-device-adapt/#the-viewport
> 
> My understanding is that as you noticed, pixel numbers on mobile are equivalent or superior to desk/laptops but pixel density is much higher on mobile, so there is a need to tell the browser not to consider how many pixels are required to display a given content but on which viewport is actually is displayed.
> 
> https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b
> 
> and
> 
> https://www.quirksmode.org/mobile/viewports2.html
> 
> I still need to wrap my mind around all that but it will make sense eventually :) I'm going to spend a few days reading all that and practicing...
> 
>>> 3) then I put all that online and now the sample that I presented yesterday
>>> works perfectly well on a small mobile device, as you wanted.
>> 
>> Portrait mode now looks great, indeed, thanks.
>> 
>> In landscape mode, tho, the browser is wide enough that the top-header
>> fits on a single line and hence "sticks around" when you scroll, thus
>> eating up a lot of screen real estate (especially since phones nowadays
>> have an appalling aspect ratio, very far from the beloved 4:3).
> 
> Ooops. Ok, I'm working on that...

Ok, it should work now, with the extra bonus that if your desktop browser window is not high enough, the behavior will be the same as landscape mobile: the menu will stay at the top of the page in "summarized" mode.

@media (max-width: 40em), (max-height: 40em) and (orientation:landscape) {

The ", " stands for "OR".

I'm regenerating the whole html set to see how that looks with other manuals.

To reproduce what I did locally:

Change the Makefile files for the various manuals to add

HTML_OPTS = --no-split --html --css-ref=emacs.css -c EXTRA_HEAD="<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">"

or

HTML_OPTS = --html --css-ref=emacs.css -c EXTRA_HEAD="<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">"

if you want to have a split manual.

Generate the doc as usual and put your own "emacs.css" responsive design css in the package (mine is here:
https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css)


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

Re: html manual +css

[Stefan Monnier]

>> The MDN doc on viewport is here:
>> https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag
>>
>> The W3C is trying to port that directly to CSS but the spec is only a draft:
>> https://drafts.csswg.org/css-device-adapt/#the-viewport

So, IIUC in the long run we don't need to change the HTML because this
`meta` element is only a hack added by Safari and the corresponding
standard feature is not yet standardized but will likely put the
corresponding info in the CSS.

>> https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b

This page is pretty poor, not explaining what the "CSS pixel" is
supposed to represent; taking "browser provided data" as gospel ;-)

> Ok, it should work now, with the extra bonus that if your desktop browser
> window is not high enough, the behavior will be the same as landscape
> mobile: the menu will stay at the top of the page in "summarized" mode.
>
> @media (max-width: 40em), (max-height: 40em) and (orientation:landscape) {

It's indeed better but with one regression: now in landscape on my
phone, the top-line is spread as a "vertical menu" whereas it used to
fit on a single line.


        Stefan

Re: html manual +css

[Yuri Khan]

On Thu, 26 Dec 2019 at 22:51, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> >> https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b
>
> This page is pretty poor, not explaining what the "CSS pixel" is
> supposed to represent; taking "browser provided data" as gospel ;-)

The CSS pixel is defined in the CSS specification.

https://drafts.csswg.org/css-values-3/#reference-pixel

Specifically, for screen devices, it recommends that 1px be an integer
multiple of a device pixel that at the typical viewing distance yields
the best approximation of a visual angle of a length of 1/96 inch at
one standard arm’s length.

Re: html manual +css

[Stefan Monnier]

>> https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b
>>
>> This page is pretty poor, not explaining what the "CSS pixel" is
>> supposed to represent; taking "browser provided data" as gospel ;-)
>
> The CSS pixel is defined in the CSS specification.
>
> https://drafts.csswg.org/css-values-3/#reference-pixel

Yes, yes, I'm aware of that.  But the above page was obviously written
for people who don't and their "explanation" just encourages the kind of
mindless web design where the "designer" tries it on a couple devices
and uses this as his "definition" of what can happen, rather than to
think about what he really wants to get in general (from which the right
behavior should derive naturally for "any" circumstance).

> Specifically, for screen devices, it recommends that 1px be an integer
> multiple of a device pixel that at the typical viewing distance yields
> the best approximation of a visual angle of a length of 1/96 inch at
> one standard arm’s length.

And of course, the best setting depends on the user's visual acuity,
which in turn can depend on circumstances ;-)


        Stefan

Re: html manual +css

[Jean-Christophe Helary]

> On Dec 27, 2019, at 0:50, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>> The MDN doc on viewport is here:
>>> https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag
>>> 
>>> The W3C is trying to port that directly to CSS but the spec is only a draft:
>>> https://drafts.csswg.org/css-device-adapt/#the-viewport
> 
> So, IIUC in the long run we don't need to change the HTML because this
> `meta` element is only a hack added by Safari and the corresponding
> standard feature is not yet standardized but will likely put the
> corresponding info in the CSS.

Not really. The feature was added by Apple/mobile Safari because it was the first to provide a full-browser application on a small screen but other vendors are now using the feature and as the MDN site says:

> A typical mobile-optimized site contains something like the following:
> 
> <meta name="viewport" content="width=device-width, initial-scale=1">

So it's not targeting mobile Safari anymore but any standard browser on the existing mobile platforms.

i.e., you'd see the same with Chrome on Android as you'd see on Safari/iOS.

For ex. this site gives screen sizes for all sorts of devices:
https://mediag.com/blog/popular-screen-resolutions-designing-for-all/

Regarding the "long run" remark, the CSS property has been proposed in 2011 and the document is still a working draft with Firefox and Safari not supporting the features (Chrome/Edge/Internet Explorer do). Also, the implementation seems to try to copy Apple's original proposal... Politics !!!

So it looks like we're in for some time. Although I just asked extra info on reddit regarding the state of the spec.

>>> https://medium.com/@elad/understanding-the-difference-between-css-resolution-and-device-resolution-28acae23da0b
> 
> This page is pretty poor, not explaining what the "CSS pixel" is
> supposed to represent; taking "browser provided data" as gospel ;-)

:)

>> Ok, it should work now, with the extra bonus that if your desktop browser
>> window is not high enough, the behavior will be the same as landscape
>> mobile: the menu will stay at the top of the page in "summarized" mode.
>> 
>> @media (max-width: 40em), (max-height: 40em) and (orientation:landscape) {
> 
> It's indeed better but with one regression: now in landscape on my
> phone, the top-line is spread as a "vertical menu" whereas it used to
> fit on a single line.

You're right.

I split the query in two:

@media (max-height: 40em) and (orientation:landscape) {
  div.header {
      position: static;
      border-color: brown;
      width: fit-content;
  }    
}

@media (max-width: 40em) {
  div.header {
      position: static;
      border-color: brown;
      width: fit-content;
  }

and if the landscape mode has enough width then it won't get the extra menu modifications that are set by max-width.


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

Re: html manual +css

[Jean-Christophe Helary]

> On 2019/12/27, at 0:50, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>> The MDN doc on viewport is here:
>>> https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag
>>> 
>>> The W3C is trying to port that directly to CSS but the spec is only a draft:
>>> https://drafts.csswg.org/css-device-adapt/#the-viewport
> 
> So, IIUC in the long run we don't need to change the HTML because this
> `meta` element is only a hack added by Safari and the corresponding
> standard feature is not yet standardized but will likely put the
> corresponding info in the CSS.

The gnu project web site uses viewport too:

https://www.gnu.org
<meta name="viewport" content="width=device-width, initial-scale=1" />


The emacs site does too:

https://www.gnu.org/software/emacs/
<meta name="viewport" content="initial-scale=1.0,maximum-scale=1.0,width=device-width" />


The emacs manual page does too:
https://www.gnu.org/software/emacs/manual/
<meta name="viewport" content="width=device-width, initial-scale=1" />


But, for reasons related to the way the emacs html manual is built, I suppose, the html manual proper does not.
https://www.gnu.org/software/emacs/manual/html_node/emacs/index.html




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

Re: html manual +css

[Gavin Smith]

On Mon, Dec 23, 2019 at 5:02 PM Jean-Christophe Helary
<jean.christophe.helary@gmail.com> 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
>
> The css I wrote:
> https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css

This looks quite good.

> It is something I had done a while ago so I just spent a few hours today cleaning it up but I'm really not sure how I came up with the various values anymore :)
>
> Anyway, if it looks useful I'd like to think of ways to have it more widely used.
>
> Also, there are plenty of things that would be nice to have but in a way we're hitting the limits of the texinfo output (and my css skills too, of course).
>
> For ex:
>
> @deffn Command find-file filename &optional wildcards
>
> becomes
>
> <dt id="index-find_002dfile">Command: <strong>find-file</strong> <em>filename &amp;optional wildcards</em></dt>
>
> it would be nice to have the arguments tagged individually and the &optional or &rest keywords tagged in a different way. Also to have the various templates identified for what they are.

Possibly: this should be possible if somebody would implement it in
texi2any. texinfo.tex already detects the &optional keyword and
outputs it in boldface.

> Also, examples should have similar tagging:
>
> @smallexample
> (switch-to-buffer (find-file-noselect filename nil nil wildcards))
> @end smallexample
>
> could be something like
>
> @smallexample
> (@commandname switch-to-buffer (@commandname find-file-noselect @arguments filename nil nil wildcards))
> @end smallexample
>
> so that we can have ways to target their contents with css.

The Guix developers managed to implement syntax highlighting by
post-processing the HTML.
(https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html)

Re: html manual +css

[Jean-Christophe Helary]

Thank you for the reply Gavin.

> On Jan 15, 2020, at 20:20, Gavin Smith <gavinsmith0123@gmail.com> 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
>> 
>> The css I wrote:
>> https://github.com/brandelune/brandelune.github.io/blob/gh-pages/code/emacs.css
> 
> This looks quite good.

If you change the width, or look at the file in a mobile phone or table the menu should be able to change.

Also, I've put online the emacs manuals for real life testing of that css, if you want to try other manuals (they all share the same css so it's not very exciting) you can find the set here:

https://doublet.jp/gnu/

I'll probably remove the set when I am done testing.

>> Also, there are plenty of things that would be nice to have but in a way we're hitting the limits of the texinfo output (and my css skills too, of course).
>> 
>> For ex:
>> 
>> @deffn Command find-file filename &optional wildcards
>> 
>> becomes
>> 
>> <dt id="index-find_002dfile">Command: <strong>find-file</strong> <em>filename &amp;optional wildcards</em></dt>
>> 
>> it would be nice to have the arguments tagged individually and the &optional or &rest keywords tagged in a different way. Also to have the various templates identified for what they are.
> 
> Possibly: this should be possible if somebody would implement it in
> texi2any. texinfo.tex already detects the &optional keyword and
> outputs it in boldface.

Thank you for the hints.

>> Also, examples should have similar tagging:
>> 
>> @smallexample
>> (switch-to-buffer (find-file-noselect filename nil nil wildcards))
>> @end smallexample
>> 
>> could be something like
>> 
>> @smallexample
>> (@commandname switch-to-buffer (@commandname find-file-noselect @arguments filename nil nil wildcards))
>> @end smallexample
>> 
>> so that we can have ways to target their contents with css.
> 
> The Guix developers managed to implement syntax highlighting by
> post-processing the HTML.
> (https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html)

Wow, I just checked this page:
https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html

and the source if full of css "hooks" even for the parens in the code...

What they do is interesting, and I guess some kind of postprocessing would be possible to achieve what I suggest, but instead of that, I'm guessing that just having texinfo add the css selectors would be easier.

Your video too is quite exciting, in the end that would be nice to have a number of css variations if you manage to complete the system.

Also, what's interesting with the current HTML export is that even though it is quite "old" in terms of standard (supposed to accept HTML 3.2 if I remember correctly ?) adding appropriate classes and IDs is just enough to access even bleeding edge CSS. Hence the idea of adding the appropriate "hooks" directly from texinfo.


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

Re: html manual +css

[Patrice Dumas]

On Wed, Jan 15, 2020 at 09:12:15PM +0900, Jean-Christophe Helary wrote:
> > 
> > The Guix developers managed to implement syntax highlighting by
> > post-processing the HTML.
> > (https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html)
> 
> Wow, I just checked this page:
> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
> 
> and the source if full of css "hooks" even for the parens in the code...
> 
> What they do is interesting, and I guess some kind of postprocessing would be possible to achieve what I suggest, but instead of that, I'm guessing that just having texinfo add the css selectors would be easier.

There are already hooks to customize the HTML produced, but it requires
knowing perl and digging into the HTML customization API which is not
documented anywhere.

My wild guess is that it could be possible to generate the same output
using this facility, maybe using something similar with how @math and 
@tex blocks are processed by outside commands in tp/init/latex2html.pm
or tp/init/tex4ht.pm.  I do not know if it is the best way, though,
maybe it makes sense to use guile to highlight code in the guile manual.

> Also, what's interesting with the current HTML export is that even though it is quite "old" in terms of standard (supposed to accept HTML 3.2 if I remember correctly ?) adding appropriate classes and IDs is just enough to access even bleeding edge CSS. Hence the idea of adding the appropriate "hooks" directly from texinfo.

Currently the default is 4.01 Transitional.  But there is a
customization file to produce HTML 3.2 in tp/init/html32.pm.

-- 
Pat

Re: html manual +css

[Jean-Christophe Helary]

> On Jan 15, 2020, at 22:43, Patrice Dumas <pertusus@free.fr> wrote:
> 
> On Wed, Jan 15, 2020 at 09:12:15PM +0900, Jean-Christophe Helary wrote:
>>> 
>>> The Guix developers managed to implement syntax highlighting by
>>> post-processing the HTML.
>>> (https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html)
>> 
>> Wow, I just checked this page:
>> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
>> 
>> and the source if full of css "hooks" even for the parens in the code...
>> 
>> What they do is interesting, and I guess some kind of postprocessing would be possible to achieve what I suggest, but instead of that, I'm guessing that just having texinfo add the css selectors would be easier.
> 
> There are already hooks to customize the HTML produced, but it requires
> knowing perl and digging into the HTML customization API which is not
> documented anywhere.

Are you talking about HTML.pm ?

>> Also, what's interesting with the current HTML export is that even though it is quite "old" in terms of standard (supposed to accept HTML 3.2 if I remember correctly ?) adding appropriate classes and IDs is just enough to access even bleeding edge CSS. Hence the idea of adding the appropriate "hooks" directly from texinfo.
> 
> Currently the default is 4.01 Transitional.  But there is a
> customization file to produce HTML 3.2 in tp/init/html32.pm.

The default is high enough that it allows for <div>, <span>, class and id. That's all we need to make good use of CSS selectors.


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

Re: html manual +css

[Patrice Dumas]

On Wed, Jan 15, 2020 at 10:52:06PM +0900, Jean-Christophe Helary wrote:
> 
> 
> > On Jan 15, 2020, at 22:43, Patrice Dumas <pertusus@free.fr> wrote:
> > 
> > On Wed, Jan 15, 2020 at 09:12:15PM +0900, Jean-Christophe Helary wrote:
> >>> 
> >>> The Guix developers managed to implement syntax highlighting by
> >>> post-processing the HTML.
> >>> (https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html)
> >> 
> >> Wow, I just checked this page:
> >> https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html
> >> 
> >> and the source if full of css "hooks" even for the parens in the code...
> >> 
> >> What they do is interesting, and I guess some kind of postprocessing would be possible to achieve what I suggest, but instead of that, I'm guessing that just having texinfo add the css selectors would be easier.
> > 
> > There are already hooks to customize the HTML produced, but it requires
> > knowing perl and digging into the HTML customization API which is not
> > documented anywhere.
> 
> Are you talking about HTML.pm ?

Yes.

-- 
Pat