Improving the presentation of Emacs user documentation

Improving the presentation of Emacs user documentation

[John Wiegley]

A Spacemacs user just showed me:

    http://spacemacs.org/doc/DOCUMENTATION.html

And compared it to:

    https://www.gnu.org/software/emacs/manual/html_mono/emacs.html

Maybe someone would like to bridge the visual gap? :)

Spacemacs not only has a cleaner or more modern look, but it makes the
documentation *feel* more accessible, which is key.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Improving the presentation of Emacs user documentation

[Xue Fuqiao]

On Mon, Feb 8, 2016 at 7:19 AM, John Wiegley <jwiegley@gmail.com> wrote:
> A Spacemacs user just showed me:
>
>     http://spacemacs.org/doc/DOCUMENTATION.html
>
> And compared it to:
>
>     https://www.gnu.org/software/emacs/manual/html_mono/emacs.html

As a relatively new Spacemacs user, here are some problems I see in the
Spacemacs docs:

1. There is no indices[1][2].

2. The anchors are unstable, like the '#orgheadline180' part in:
http://spacemacs.org/doc/DOCUMENTATION.html#orgheadline180
Although Emacs's URIs are not permanent either[3], Spacemacs's links are even
more unstable.

3. I can't use convenient key bindings in Info like 'm', '1 .. 9', 'n', 'p', and
'^' to browse Spacemacs's docs.

Anyway, the CSS styles of the Spacemacs docs are beautiful.

Footnotes:

[1] https://www.gnu.org/software/emacs/manual/html_node/emacs/Concept-Index.html#Concept-Index
[2] https://www.gnu.org/software/emacs/manual/html_node/elisp/Index.html#Index
[3] https://lists.gnu.org/archive/html/emacs-devel/2016-01/msg00079.html

Re: Improving the presentation of Emacs user documentation

[Xue Fuqiao]

On Mon, Feb 8, 2016 at 10:49 AM, Xue Fuqiao <xfq.free@gmail.com> wrote:

> 3. I can't use convenient key bindings in Info like 'm', '1 .. 9', 'n', 'p', and
> '^' to browse Spacemacs's docs.

And Spacemacs developers refused to write documentation in Texinfo:

https://github.com/syl20bnr/spacemacs/issues/1568#issuecomment-111311244

Re: Improving the presentation of Emacs user documentation

[Andreas Röhler]

On 08.02.2016 00:19, John Wiegley wrote:
> A Spacemacs user just showed me:
>
>      http://spacemacs.org/doc/DOCUMENTATION.html
>
> And compared it to:
>
>      https://www.gnu.org/software/emacs/manual/html_mono/emacs.html
>
> Maybe someone would like to bridge the visual gap? :)
>
> Spacemacs not only has a cleaner or more modern look, but it makes the
> documentation *feel* more accessible, which is key.
>

Hmm, IMHO spacemacs took a wrong path relying on some features which 
make things more complicated at the bottom.

WRT to documentation here: initial tutorial still focuses on keys where 
it should start with mnemonic command-names.

See first entry of M-v.

Cheers,

Andreas

Re: Improving the presentation of Emacs user documentation

[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. ]]]

To change the look of Emacs documentation calls for an HTML-Info to
replace the existing Info format from 1975.  We are waiting for
someone who wants to do it.

-- 
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: Improving the presentation of Emacs user documentation

[Nicolas Petton]

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

Richard Stallman <rms@gnu.org> writes:

> To change the look of Emacs documentation calls for an HTML-Info to
> replace the existing Info format from 1975.  We are waiting for
> someone who wants to do it.

Couldn't we just style the HTML pages?

(If so, you just got a volunteer to do it)

Cheers,
Nico

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

Re: Improving the presentation of Emacs user documentation

[Stefan Monnier]

>     https://www.gnu.org/software/emacs/manual/html_mono/emacs.html

Incidentally, this hang my Iceweasel,


        Stefan

Re: Improving the presentation of Emacs user documentation

[Stefan Monnier]

> Couldn't we just style the HTML pages?

To a large extent, yes, tho it may require changes to the texi2html
converter as well.

> (If so, you just got a volunteer to do it)

IIUC the same style is used (or should be used) for all GNU manuals in
www.gnu.org, so improvements would benefit a lot of people.


        Stefan

Re: Improving the presentation of Emacs user documentation

[Andreas Schwab]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>     https://www.gnu.org/software/emacs/manual/html_mono/emacs.html
>
> Incidentally, this hang my Iceweasel,

You probably just have to wait a bit longer, the page is huge.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: Improving the presentation of Emacs user documentation

[John Wiegley]

>>>>> Nicolas Petton <nicolas@petton.fr> writes:

> Couldn't we just style the HTML pages?
> (If so, you just got a volunteer to do it)

Awesome. Feel free to dig into texi2html, plus better CSS. Double bonus if it
looks great in eww and on mobile.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

RE: Improving the presentation of Emacs user documentation

[Drew Adams]

> > Couldn't we just style the HTML pages?
> > (If so, you just got a volunteer to do it)
> 
> Awesome. Feel free to dig into texi2html, plus better CSS. Double bonus if
> it looks great in eww and on mobile.

On this topic, and not contradicting what others have said AFAIK, this is
my thought:

It would be good to start with _accessibility_ and only later go on to
visual styling, making sure that it doesn't mess up accessibility.

Starting with making things look cool, if paying no attention to at least
minimal accessibility concerns, is not particularly stylish or cool. ;-)

(Just one opinion.)

Re: Improving the presentation of Emacs user documentation

[Marcin Borkowski]

On 2016-02-08, at 17:22, Drew Adams <drew.adams@oracle.com> wrote:

>> > Couldn't we just style the HTML pages?
>> > (If so, you just got a volunteer to do it)
>> 
>> Awesome. Feel free to dig into texi2html, plus better CSS. Double bonus if
>> it looks great in eww and on mobile.
>
> On this topic, and not contradicting what others have said AFAIK, this is
> my thought:
>
> It would be good to start with _accessibility_ and only later go on to
> visual styling, making sure that it doesn't mess up accessibility.
>
> Starting with making things look cool, if paying no attention to at least
> minimal accessibility concerns, is not particularly stylish or cool. ;-)
>
> (Just one opinion.)

I'm not an expert on CSS, but AFAIK, accesib

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Improving the presentation of Emacs user documentation

[Marcin Borkowski]

On 2016-02-08, at 17:22, Drew Adams <drew.adams@oracle.com> wrote:

>> > Couldn't we just style the HTML pages?
>> > (If so, you just got a volunteer to do it)
>> 
>> Awesome. Feel free to dig into texi2html, plus better CSS. Double bonus if
>> it looks great in eww and on mobile.
>
> On this topic, and not contradicting what others have said AFAIK, this is
> my thought:
>
> It would be good to start with _accessibility_ and only later go on to
> visual styling, making sure that it doesn't mess up accessibility.
>
> Starting with making things look cool, if paying no attention to at least
> minimal accessibility concerns, is not particularly stylish or cool. ;-)
>
> (Just one opinion.)

I'm not an expert on CSS, but AFAIK, accessibility is orthogonal to
presentation if done correctly through CSS.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Improving the presentation of Emacs user documentation

[Nicolas Petton]

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

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> Nicolas Petton <nicolas@petton.fr> writes:
>
>> Couldn't we just style the HTML pages?
>> (If so, you just got a volunteer to do it)
>
> Awesome. Feel free to dig into texi2html, plus better CSS. Double bonus if it
> looks great in eww and on mobile.

I will make sure it looks good in both.

Nico

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

RE: Improving the presentation of Emacs user documentation

[Nicolas Petton]

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

Drew Adams <drew.adams@oracle.com> writes:

> It would be good to start with _accessibility_ and only later go on to
> visual styling, making sure that it doesn't mess up accessibility.

I'll be careful about this.

Nico

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

RE: Improving the presentation of Emacs user documentation

[Drew Adams]

> > It would be good to start with _accessibility_ and only later go on to
> > visual styling, making sure that it doesn't mess up accessibility.
> 
> I'll be careful about this.

Great. Thx.

Re: Improving the presentation of Emacs user documentation

[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. ]]]

  > Couldn't we just style the HTML pages?

  > (If so, you just got a volunteer to do it)

If that is an improvement over the present situation, I have nothing
against it.   Remember that we are talking about the pages of the manual,
not the pages that you are developing.


-- 
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: Improving the presentation of Emacs user documentation

[Nicolas Petton]

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

Richard Stallman <rms@gnu.org> writes:

> Remember that we are talking about the pages of the manual,
> not the pages that you are developing.

Yes, I know.

Nico

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

Re: Improving the presentation of Emacs user documentation

[Julius Pfrommer]

John Wiegley:
> Awesome. Feel free to dig into texi2html, plus better CSS. Double
> bonus if it looks great in eww and on mobile.

There may be a low-cost solution with almost equal results.

Many projects use Sphinx [1] to render their documentation to html.
The look-and-feel of the generated html is selected via themes. Some of
the themes look very similar to the spacemacs example [2].

Somebody already wrote a tool that converts the GCC texinfo
documentation to rst (restructured text), that can then be fed into
Sphinx:
https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01030.html

Depending on the maturity of the conversion, this could be an
alternative build chain to render the documentation to html without
changing the input format. Also, Sphinx can generate good-looking PDFs
and more formats.

[1] http://www.sphinx-doc.org/en/stable/
[2] http://read-the-docs.readthedocs.org/en/latest/theme.html

Re: Improving the presentation of Emacs user documentation

[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. ]]]

  > Somebody already wrote a tool that converts the GCC texinfo
  > documentation to rst (restructured text), that can then be fed into
  > Sphinx:
  > https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01030.html

Would people look at the results
and see if it has the features we would like to have
in HTML intended to replace the Info format?

-- 
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: Improving the presentation of Emacs user documentation

[Marcin Borkowski]

On 2016-02-11, at 19:17, Richard Stallman <rms@gnu.org> wrote:

>   > Somebody already wrote a tool that converts the GCC texinfo
>   > documentation to rst (restructured text), that can then be fed into
>   > Sphinx:
>   > https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01030.html
>
> Would people look at the results
> and see if it has the features we would like to have
> in HTML intended to replace the Info format?

I thought the general consensus was that we would _not_ like to replace
the Info format...

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Improving the presentation of Emacs user documentation

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Date: Thu, 11 Feb 2016 19:23:16 +0100
> Cc: jwiegley@gmail.com, Julius Pfrommer <julius.pfrommer@kit.edu>,
> 	emacs-devel@gnu.org
> 
> On 2016-02-11, at 19:17, Richard Stallman <rms@gnu.org> wrote:
> 
> >   > Somebody already wrote a tool that converts the GCC texinfo
> >   > documentation to rst (restructured text), that can then be fed into
> >   > Sphinx:
> >   > https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01030.html
> >
> > Would people look at the results
> > and see if it has the features we would like to have
> > in HTML intended to replace the Info format?
> 
> I thought the general consensus was that we would _not_ like to replace
> the Info format...

No, you misunderstood.  We don't want to replace Texinfo as the source
language, but having an HTML-based documentation reader that is
otherwise as capable as the Info readers we have is definitely a
desirable direction.

Re: Improving the presentation of Emacs user documentation

[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. ]]]

  > I thought the general consensus was that we would _not_ like to replace
  > the Info format...

It is the GNU Project's goal to replace it with an HTML-based format
that (1) can be viewed in any browser but (2) has additional data
to support all the Info features, in a browser specifically set up
to understand them.

We want to generate this from Texinfo sources, so we can also run
them through TeX.


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