Some concrete problems with the SWI-Prolog documentation site comment box

SWI-Prolog web site and services
,
1

What I noticed:

  • Are the comments synchronized between the eu and the www site? I doesn’t seem to be the case.
  • Terminating a list works … if it is indented. If it is not (if the marks start in the first column), the text following the list remains indented; one can only get rid of that by inserting a new header. This should probably work whether indented or not.
  • The library(foo) automatic linking directs to the page w/o left sidebar, e.g. directly to https://eu.swi-prolog.org/pldoc/doc/_SWI_/library/error.pl instead of https://www.swi-prolog.org/pldoc/man?section=error
  • Autolinking to functions seems to not work. E.g. a link to random_float/0 stays dead.
  • The markup processor gets confused if you write [random_float](https://eu.swi-prolog.org/pldoc/doc_for?object=f(random_float/0)) … by the dual termination paranthesis. The last parenthesis is regarded as not being part of the URL.
  • If you have a reference e.g. library(error) in a header, it is rendered in blue on blue and becomes invisible
  • *CTRL-C should not be shortcut to insert “teletype markup” (i.e. the = sign). My muscle memory cannot adapt, this is torture.
  • I still don’t know how to make “teletype mode” (started and ended with =) work properly. Sometimes it works, sometimes it doesn’t. I think there are too many extra cases and there is no way to properly find out where “teletype mode” starts and ends (obviously, in a programming language that contains itself the markup character). Can’t one just use in replacement? Note that backticks instead of = give italics instead of teletype. Maybe change that and deprecate the single =?
  • Note that the = stays in if auto-quoting kicks in, For example the markup =error(type_error(,),Extra)= leads ot a teleytped error(type_error(_,_),Extra) surround by equal signs.
  • There is a special “quoting mode” of sections; introduced with ~~~~ which makes them look like code (which I never use, == is my friend) but no special mode for italicization.
  • If you have two comments on a page, hitting edit will always start editing the last comment you entered, not the comment on which you hit edit.
1 Like
2

I think the entire thing needs rethinking. One of the solutions that comes to mind is that when we start hosting Discourse ourselves and limits no longer apply and we can have arbitrary plugins we could auto-link between web pages and discourse.

Thus, a web page on SWI-Prolog should show a connected Discourse topic if no such topic exists a single click should go to Discourse and create a topic for the page. We can choose between either showing the Discourse topic on the page (not sure this can be done in a compact way) or merely indicate the page is being discussed at Discourse and a link should get you to it.

2 Likes
3

Discourse plugins (ref 1)

FYI for all considering this.

If you want to create a plugin you will need a development environment, see: Discourse category howto developers dev -install and choose one. I have personally created a development environment using the Windows 10 version which makes use of WSL 2 and Ubuntu version.

The toolchain is different; Ruby 2.6+, PostgreSQL 10+, Redis 4.0+, Ember.js (ref 1) (ref 2) and just recently they moved up to PostgreSQL 12 (ref 1)

I have no experience with most of this except for years of experience with SQL databases, but not specifically PostgreSQL which I am quickly gaining.

Don’t be surprised if we learn to bypass some of the tools like Ruby and start using Prolog to create plugins.

You will not have the ability to install a plugin into the production version of this site, for that you will need the assistance of the admins on this site.

Obviously a plugin will have to be carefully checked and tested before being installed and and the discussion on how to do that has not started.

1 Like