move FAQ and INSTALL to .rst format

[Ralf Hemmecke]

I have now converted (not yet completely perfect) some files to
reStructuredText format so that they can be shown nicely on
fricas.github.io.

FAQ --> src/doc/sphinx/source/faq.rst
INSTALL --> src/doc/sphinx/source/install.rst
README --> README.rst

While the README.rst now shows (with links) on the initial github page

https://github.com/hemmecke/fricas/tree/rstdoc
(my rstdoc branch as example)

the other files look like this:

https://hemmecke.github.io/fricas/faq.html
https://hemmecke.github.io/fricas/install.html

That would make it easier to point users to the exact place when someone
asks on the mailing list.

Somebody against integrating FAQ and install description into the web
documentation?

If not, I will clean up and send a pull request.

Ralf

[Waldek Hebisch]

In lynx current INSTALL shows nicer than the new version. INSTALL
should be readable as plain text and it is in toplevel directory
so that users can find it easily. Similarly README. FAQ is less
critical but also deserves to be at top level. AFAICS web servers
have no trouble showing text files. So only potential gain
is due to added links. However README is pretty short and
INSTALL is rather easy to navigate using text search, so
IMO gain from links is marginal.

The .rst files when viewed as plain text do not look bad,
however in total this change for me looks like unnecessary
complication.

--
Waldek Hebisch

[Ralf Hemmecke]

> In lynx current INSTALL shows nicer than the new version.

Huh, you read text files with lynx?

> INSTALL should be readable as plain text and it is in toplevel
> directory so that users can find it easily. Similarly README.

I have not removed them. But now they point to the .rst version or the
.html version on the web.

And you must admit reStructuredText is pretty readable even as plain
text file.

> FAQ is less critical but also deserves to be at top level.

There is also a link in the top-level FAQ file.

> AFAICS web servers have no trouble showing text files. So only
> potential gain is due to added links.

You miss my whole point. I want to make information more visible. For
that I started the whole fricas.github.io business. If you now tell me
that I should just display plain text files where a simple change to
.rst would look much nicer for most people reading at fricas.github.io,
that would be counterproductive.

> However README is pretty short and INSTALL is rather easy to navigate
> using text search, so IMO gain from links is marginal.

> The .rst files when viewed as plain text do not look bad, however in
> total this change for me looks like unnecessary complication.

OK this sounds not like you are totally against it. Since I maintain the
documentation part, I understand this as a "go on". Note that I would
like to bring most of the documentation to fricas.github.io and make it
easier for contributors to jump in.

Have you ever pressed the "edit on github" link that appears, for
example at the right box at http://fricas.github.io/features.html or at
the top of http://fricas.github.io/api/Algebra.html ?
(But please try it with Firefox or Chrome. Lynx will most probably not
be so nice --- sorry, but I cannot test lynx --- I would have to learn
too much I don't need.)
When detecting errors on the page, people can press the link, edit the
file online and by saving it automatically send a pull request.

The reStructuredText format is probably not for you, but please do not
stop me from using it to try to attract new users.

Ralf

[Dima Pasechnik]

Certainly these docs are much nicer in rst than in plain text - although I would use markdown (md) format, which is easier in many ways.

--
You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/fricas-devel/4587839f-66b2-301d-4800-69050edfeaab%40hemmecke.org.

[Ralf Hemmecke]

On 10/3/20 10:11 AM, Dima Pasechnik wrote:
> Certainly these docs are much nicer in rst than in plain text - although I
> would use markdown (md) format, which is easier in many ways.

I considered Markdown, but decided against it for two reasons.
1) Sphinx uses rst by default and sphinx was more important for
the whold documentation effort.
2) Markdown is ambiguous and there are too many variants.
(github-flavored markdown, commonmark, etc.)

Since adding INSTALL and FAQ to the web makes sense, using rst instead
of md would not introduce yet another markup language.

Ralf

[Dima Pasechnik]

On Sat, 3 Oct 2020, 09:50 Ralf Hemmecke, <ra...@hemmecke.org> wrote:

On 10/3/20 10:11 AM, Dima Pasechnik wrote:
> Certainly these docs are much nicer in rst than in plain text - although I
> would use markdown (md) format, which is easier in many ways.

I considered Markdown, but decided against it for two reasons.
1) Sphinx uses rst by default and sphinx was more important for
   the whold documentation effort.

sphinx  handles markdown just as well, with one extra package installed.

2) Markdown is ambiguous and there are too many variants.
   (github-flavored markdown, commonmark, etc.)

Since adding INSTALL and FAQ to the web makes sense, using rst instead
of md would not introduce yet another markup language.

Do you have any rst files, or are (planning to start) generating them automatically,

using sphinx lisp? 

If there is anything to learn about the use of sphinx in SageMath, stay away from attempts

to speed it up used handwritten extensions.

And rst syntax is hard to get right, it's a constant struggle in SageMath.

 

Ralf

--
You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/fricas-devel/d2976912-c485-3487-30ef-d4dde43cc3d8%40hemmecke.org.

[Samuel Lelièvre]

Have a look at MyST:

  MyST - Markedly Structured Text

  - docs: https://myst-parser.readthedocs.io/en/latest/

  - repo: https://github.com/executablebooks/myst-parser