INSTALL

[Waldek Hebisch]

After more careful look at 'install.rst' I think that for now we
should go with plain text version. Namely, unlike README,
.rst version looks significantly worse than plain text version.


--
Waldek Hebisch

[Ralf Hemmecke]

> After more careful look at 'install.rst' I think that for now we
> should go with plain text version. Namely, unlike README,
> .rst version looks significantly worse than plain text version.

What do you mean by "worse"?
That you have to write verbose inline stuff inside ``...``?
That verbose code has to be put indented after a :: ?
That different title lines have to be followed by some underlining?

That is basically all of the markup I used.

What you basically say is, that my conversion was work-done-for-nothing.

My concern is now that you change the current INSTALL file.
Synchronization with my install.rst will be hard since I restructured a
bit. Are you afraid of writing .rst stuff or do you think that my
install.rst is not nicely readable as plain text? I definitely want
install.rst on the web and showing a plain text file on an otherwise
sphinx-generated site would look very unprofessional.

Can we make a compromise that you modify install.rst content-wise and I
add/correct the respective rst markup?

Ralf

[Dima Pasechnik]

there is
https://github.com/fricas/fricas/pull/45 - not sure whether this is
what one discusses here.

Needless to say, 99% of people would read INSTALL in the browser,
keeping it plaintext in 2021 is
out of touch with the reality.

> --
> 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/18c57d99-083d-6276-b9fe-3ef5b8f189ef%40hemmecke.org.

[Waldek Hebisch]

On Mon, Apr 19, 2021 at 08:33:02AM +0200, Ralf Hemmecke wrote:
> > After more careful look at 'install.rst' I think that for now we
> > should go with plain text version. Namely, unlike README,
> > .rst version looks significantly worse than plain text version.
>
> What do you mean by "worse"?
> That you have to write verbose inline stuff inside ``...``?
> That verbose code has to be put indented after a :: ?
> That different title lines have to be followed by some underlining?
>
> That is basically all of the markup I used.

Yes, that and |git repository| (we should have actual URL in
the file). Problem is with quantity, that is actualy more
than is some other markup formats.

> What you basically say is, that my conversion was work-done-for-nothing.

If you want to view it in this way. Not all things work as
expected/hoped for...

> My concern is now that you change the current INSTALL file.
> Synchronization with my install.rst will be hard since I restructured a
> bit. Are you afraid of writing .rst stuff or do you think that my
> install.rst is not nicely readable as plain text?

Mainly the second, INSTALL should be readable as plain text.
It is OK to have marked up version as master source. Some
markup formats can produce decent looking plain text versions
(IIUC sphinx is supposed to produce text version, but ATM
this does not work for me so in particular I can not see
if this is good enough). Another issue is dependency. .rst
is claimend to be ligtweight, but supporting programs are
rather large...

> I definitely want
> install.rst on the web and showing a plain text file on an otherwise
> sphinx-generated site would look very unprofessional.

.rst pretending to be plain text is at least as unprofessional.

--
Waldek Hebisch

[Bill Page]

-1

I disagree. Reading .rst in a text editor looks much better to me than
most people's "plain text" and of course it looks even better on a web
site or in a pdf document.

[Kurt Pagani]

On 19.04.2021 21:26, Waldek Hebisch wrote:
...

>
> Mainly the second, INSTALL should be readable as plain text.
> It is OK to have marked up version as master source. Some
> markup formats can produce decent looking plain text versions
> (IIUC sphinx is supposed to produce text version, but ATM
> this does not work for me so in particular I can not see
> if this is good enough). Another issue is dependency. .rst
> is claimend to be ligtweight, but supporting programs are
> rather large...

That's true, however, there are a lot of little helpers around, e.g.

Emacs Support for reStructuredText
https://docutils.sourceforge.io/docs/user/emacs.html

>

https://pandoc.org/MANUAL.html

This (usually) provides good results:

pandoc --from=rst --to=plain filename.rst

OTOH --from=plain --to=rst is not always what you'll expect.

[Ralf Hemmecke]

> Yes, that and |git repository| (we should have actual URL in
> the file).

We can discuss this. The |...| stuff is actually defined in conf.py.
And conf.py takes input from environment variables during "make".
This was done on purpose, since I want the web address not be hardcoded.
It should also work when I present a website at my github fork.

It would be super simple to replace |...| by an awk script.

In fact, since the markup in install.rst is soooo simple, it would be
quite easy to produce a awk script that removes |...|.

> Problem is with quantity, that is actualy more
> than is some other markup formats.

What else is TOO MUCH? Name it!

BTW, in Emacs, there is a special rstdoc mode that brings me
highlighting. Vim has probably a similar mode. It is not only YOU that
reads the install file. In fact, the younger generation is for whom we
all do this, no? What is the intended user base of FriCAS? Researchers
with age over 65?

>> What you basically say is, that my conversion was work-done-for-nothing.
> If you want to view it in this way. Not all things work as
> expected/hoped for...

Yes. But do you think that increases the amount of people working on FriCAS?

>> Are you afraid of writing .rst stuff or do you think that my
>> install.rst is not nicely readable as plain text?

> Mainly the second, INSTALL should be readable as plain text.
> It is OK to have marked up version as master source. Some
> markup formats can produce decent looking plain text versions
> (IIUC sphinx is supposed to produce text version, but ATM
> this does not work for me so in particular I can not see
> if this is good enough). Another issue is dependency. .rst
> is claimend to be ligtweight, but supporting programs are
> rather large...
>
>> I definitely want
>> install.rst on the web and showing a plain text file on an otherwise
>> sphinx-generated site would look very unprofessional.
>
> .rst pretending to be plain text is at least as unprofessional.

I never said .rst is plain text (actually it is pure ASCII). But it *is*
easily readable.

Anyway. Offer for compromise. I write a script that computes (without
sphinx) the INSTALL file from the install.rst file.

Thank you, Kurt. I attach the output of

pandoc --from rst --to plain install.rst > INSTALL

Replacing the |...| stuff before giving install.rst to pandoc would be
simple, but was not done for the attachment.

Waldek, would you be satisfied with having both
src/doc/sphinc/source/install.rst and INSTALL (generated from
install.rst)? Both committed to the git repo?

May I ask you whether you really find the attached INSTALL file easier
to read than install.rst.

Ralf

[Waldek Hebisch]

On Tue, Apr 20, 2021 at 12:25:51AM +0200, Ralf Hemmecke wrote:
>
> May I ask you whether you really find the attached INSTALL file easier
> to read than install.rst.

Yes.

I have now put updated install.rst at:

http://math.uni.wroc.pl/~hebisch/fricas/install.rst

I do not know if it will format nicely and probably there
are still things to correct. One thing to look at is list
of supported Lisp implementations: in text version web
addresses should be clearly visible.

--
Waldek Hebisch

[Ralf Hemmecke]

> http://math.uni.wroc.pl/~hebisch/fricas/install.rst

====================
0. Change to a directory with enough (0.8 GB) free space
====================

I have not checked, but the 0.8GB seem to include the whole build, right?

====================
1. Fetch sources
::

git clone --depth 1 https://github.com/fricas/fricas
cd fricas

Remove the ``--depth 1`` option for access to the change history.
====================

Is the ``--depth 1 really important to you? When I clone with depth 1
the size is

5.877.760 ./.git
31.539.200 .

without --depth the disk size is

20.582.400 ./.git
46.243.840 .

compared to what is generated later. The whole history is less than all
checked out files. Those 15 MB are negligible (also compared to the size
of the build).


====================
2. Create build directory and change to it
::

mkdir ax-build
cd ax-build
=====================

Do you want people to do the build inside a subdirectory of the
git-repository?

Why do you call it "ax-..." and not "fricas-build"?

I am more in favour of giving a concrete directory here something like

/PATH/TO/FRICAS

and

/PATH/TO/FRICAS-BUILD

(possibly putting it into variables F and B,
because calling "./configure" would not work inside "ax-build",
"$F/configure" would.

Anyway, I have changed ax-build t fricas-build.

Since I do not have "." in my PATH, also calling "configure" will not
work even in in-tree-builds.




I've added your modifications (with slight changes)

https://github.com/hemmecke/fricas/blob/wip/rstdoc/src/doc/sphinx/source/install.rst

Rendered version is here:

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

I'll look into generating a plain text INSTALL file from install.rst later.

Ralf

[Waldek Hebisch]

On Sat, Apr 24, 2021 at 10:58:35PM +0200, Ralf Hemmecke wrote:
> > http://math.uni.wroc.pl/~hebisch/fricas/install.rst
>
> ====================
> 0. Change to a directory with enough (0.8 GB) free space
> ====================
>
> I have not checked, but the 0.8GB seem to include the whole build, right?

Yes.

> ====================
> 1. Fetch sources
> ::
>
> git clone --depth 1 https://github.com/fricas/fricas
> cd fricas

^^^^^^^^^
That is not needed/wanted

>
> Remove the ``--depth 1`` option for access to the change history.
> ====================
>
> Is the ``--depth 1 really important to you? When I clone with depth 1
> the size is
>
> 5.877.760 ./.git
> 31.539.200 .
>
> without --depth the disk size is
>
> 20.582.400 ./.git
> 46.243.840 .
>
> compared to what is generated later. The whole history is less than all
> checked out files. Those 15 MB are negligible (also compared to the size
> of the build).

That is 5M to fetch versus 20M. It is likely that webby kids will
not notice, but difference is substantial for people with slower
links.

> ====================
> 2. Create build directory and change to it
> ::
>
> mkdir ax-build
> cd ax-build
> =====================
>
> Do you want people to do the build inside a subdirectory of the
> git-repository?

Parallel, see correction above. I do not know how many Mac OS
or Windows user will build git version, but for them in tree
build will fail. Even if in tree build works, parallel
directory is cleaner.

> Why do you call it "ax-..." and not "fricas-build"?

Well, that is what I use. I prefer short names, this one is
not very important except for distingushing between various
build directories (that is why "build" would be bad name).

> I am more in favour of giving a concrete directory here something like
>
> /PATH/TO/FRICAS
>
> and
>
> /PATH/TO/FRICAS-BUILD
>
> (possibly putting it into variables F and B,
> because calling "./configure" would not work inside "ax-build",
> "$F/configure" would.
>
> Anyway, I have changed ax-build t fricas-build.
>
> Since I do not have "." in my PATH, also calling "configure" will not
> work even in in-tree-builds.

Right, the configure line should be:

../fricas/configure --with-lisp=/path/to/your/lisp --prefix=/tmp/usr

And the same for '--help'

> I've added your modifications (with slight changes)
>
> https://github.com/hemmecke/fricas/blob/wip/rstdoc/src/doc/sphinx/source/install.rst
>
> Rendered version is here:
>
> https://hemmecke.github.io/fricas/install.html

In lynx names have "P:" added, like:

Installation GuideP:

AFAICS this is due to the following in generated html.

<a class="headerlink" href="#installation-guide" title="Permalink to this headline">P:</a>

More generally, generated html has a lot of Javascript junk. Is this
someting you added to configuration or general Github junk?

BTW: In current days Javascript is security problem and it would
be good if our pages worked without Javascript.

--
Waldek Hebisch

[Waldek Hebisch]

On Sun, Apr 25, 2021 at 11:23:29AM +0200, Waldek Hebisch wrote:
> On Sat, Apr 24, 2021 at 10:58:35PM +0200, Ralf Hemmecke wrote:
> > > http://math.uni.wroc.pl/~hebisch/fricas/install.rst
> >

> > I've added your modifications (with slight changes)
> >
> > https://github.com/hemmecke/fricas/blob/wip/rstdoc/src/doc/sphinx/source/install.rst
> >
> > Rendered version is here:
> >
> > https://hemmecke.github.io/fricas/install.html

I have now replaced:

http://math.uni.wroc.pl/~hebisch/fricas/install.rst

by updated version. Used 'fr-build' to make commands slightly
shorter.

BTW: Usual convention in text files is to have two spaces between
dot and following sentence. You changed all that to single space.
Any reason?

--
Waldek Hebisch

[Ralf Hemmecke]

I've added your modifications (with slight changes)

https://github.com/hemmecke/fricas/blob/wip/rstdoc/src/doc/sphinx/source/install.rst

>> Rendered version is here:

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

> In lynx names have "P:" added, like:
>
> Installation GuideP:

I do not know what version of lynx and what locale setting you have, but
in my case it shows this:

Installation Guide¶

In firefox the ¶ only appears if you hover with the mouse over the line
with a heading. And seemingly when you right-click on this ¶
(PILCROW SIGN) https://en.wikipedia.org/wiki/Pilcrow
then you can extract a link exactly to that section. I wouldn't want to
remove that feature. Unfortunately, I have no idea whether lynx is
capable of using that information instead of just showing nonsense "P:"
in your case.

> AFAICS this is due to the following in generated html.
>
> <a class="headerlink" href="#installation-guide" title="Permalink to this headline">P:</a>

Yes, perfectly fine functioning HTML, but it is ¶ instead of P: in the
.html sources.

> More generally, generated html has a lot of Javascript junk. Is this
> someting you added to configuration or general Github junk?

That is added by Sphinx. Github is only *showing* the generated HTML and
not to be blamed here. However, JavaScript is only used to get the
search field in this page working all the other stuff is working
perfectly fine with JavaScript turned off.

> BTW: In current days Javascript is security problem and it would
> be good if our pages worked without Javascript.

I usually have noscript running in Firefox and only whitelist pages I
trust. You can decide for yourself whether you trust fricas.github.io.
Even though I generally distrust javascript, it is very useful here. And
if you like, use "cd src/doc; make localdoc" to generate a version that
solely lives on your computer, disconnect from the internet and use
javascript locally.


I have now also created a shell/sed script that generates INSTALL
from install.rst.

See
https://github.com/hemmecke/fricas/blob/wip/rstdoc/generate_INSTALL.sh
and the generated result
https://github.com/hemmecke/fricas/blob/wip/rstdoc/INSTALL

Ralf

[Grégory Vanuxem]

Hello,

Le dim. 25 avr. 2021 à 12:42, Waldek Hebisch
<heb...@math.uni.wroc.pl> a écrit :

> BTW: Usual convention in text files is to have two spaces between
> dot and following sentence. You changed all that to single space.
> Any reason?

Huh? Are you sure? I'm surprised, usual convention is one space after the dot,
so one space between the dot and the following sentence. Take a look
at New York Times for example.
And this is what I learnt at school and university for academic texts.
Or do you mean plain text?


BTW, in the quick installation section you write:

configure && make && sudo make install

Shouldn't it be:

./configure && make && sudo make install

?

And last thing, I would explain what is |PACKAGE_BOOK| before since it
is mentioned above.

Cheers,