How to improve the wiki for check-ins and branches

(1.1) By Richard Hipp (drh) on 2020-04-01 17:52:07 edited from 1.0 [link] [source]

Fossil has the ability to associate a wiki page with a check-in or branch. One example of that is on the 718ead555b098 check-in of SQLite. Another example is the describe-objects-using-wiki branch of Fossil itself.

This is a powerful mechanism for documenting the history of a project. But it needs improvement. For longer wiki pages (such as the two examples above) the wiki itself takes up too much space on the page. It would be better to show just the first few lines of the wiki, then have a "Show More" button that will show the whole thing.

Technical question:

Can a skilled javascript/CSS hacker please suggest a good mechanism to implement that feature?

Maybe we should implement a general mechanism for collapsing/expanding each of the "subsections" in an /info page? Is that easy to do in CSS?

Along those some lines....

Seem like it might be useful to link a forum thread to a branch or check-in. This won't work for the default Fossil forum or SQLite forum because those forums are in separate repositories from the source tree. But, for projects that put the forum and the source tree together (example) it seems like this could be useful. Also, I was thinking that I might open up forums on the source repositories for SQLite and Fossil that are writable only by people with check-in privilege on those repos - as kind of a "dev" forum as opposed to a "user" forum, where this message is being added.

Ideas on both the technical implementation of this and on what the user interface should look like are welcomed.

(2) By Chris (crustyoz) on 2020-04-01 18:13:02 in reply to 1.1 [link] [source]

Not saying this css is an exact solution to your problem, but it is close.
I use it to hide/show answers to questions or section text under a header.

It presents a diamond to the far right of the visible header that rotates
when the line is clicked to expose the previously hidden text.

/*
  CSS only accordion

  https://www.cssscript.com/responsive-accessible-accordion-with-css3-transitions/
*/
.accordion {
  border: 1px solid black;
  padding: 0 10px;
  margin: 0 auto;
  list-style: none outside;
}

.accordion > * + * { border-top: 1px solid black; }

.accordion-item-hd {
  display: block;
  padding: 15px 30px 15px 0;
  position: relative;
  cursor: pointer;
  font-size: 18px;
  font-weight: bold;
}

.accordion-item-input:checked ~ .accordion-item-bd {
  max-height: 1000px;
  padding-top: 15px;
  margin-bottom: 15px;
  -webkit-transition: max-height 1s ease-in, margin .3s ease-in, padding .3s ease-in;
  transition: max-height 1s ease-in, margin .3s ease-in, padding .3s ease-in;
}

.accordion-item-input:checked ~ .accordion-item-hd > .accordion-item-hd-cta {
  -webkit-transform: rotate(0);
  -ms-transform: rotate(0);
  transform: rotate(0);
}

.accordion-item-hd-cta {
  display: block;
  width: 30px;
  position: absolute;
  top: calc(50% - 6px );
  /*minus half font-size*/
  right: 0;
  pointer-events: none;
  -webkit-transition: -webkit-transform .3s ease;
  transition: transform .3s ease;
  -webkit-transform: rotate(-180deg);
  -ms-transform: rotate(-180deg);
  transform: rotate(-180deg);
  text-align: center;
  font-size: 12px;
  line-height: 1;
}

.accordion-item-bd {
  max-height: 0;
  margin-bottom: 0;
  overflow: hidden;
  -webkit-transition: max-height .15s ease-out, margin-bottom .3s ease-out, padding .3s ease-out;
  transition: max-height .15s ease-out, margin-bottom .3s ease-out, padding .3s ease-out;
}

.accordion-item-input {
  clip: rect(0 0 0 0);
  width: 1px;
  height: 1px;
  margin: -1;
  overflow: hidden;
  position: absolute;
  left: -9999px;
}

(3) By smartmic on 2020-04-01 21:10:21 in reply to 1.1 [link] [source]

Concerning long wiki pages: A simple solution that circumvents Javascript and complex CSS could be to use the tag of HTML5

(4.1) By Joel Dueck (joeld) on 2020-04-01 21:48:59 edited from 4.0 in reply to 1.1 [link] [source]

The <detail> and <summary> tags in HTML5 are intended for this kind of toggle-able content. See https://www.geeksforgeeks.org/html5-details-tag/

(Edit to add: I would like to see this markup used in several other places as well. If amenable, maybe I can work on a patch.)

(5) By Richard Hipp (drh) on 2020-04-02 00:23:41 in reply to 4.1 [source]

I would very much like to see that patch. Thanks.

In the meantime, I have crude accordion menus in a branch. Example pages:

There is lots of room for UX improvement here, especially with some of the alternative skins:

Patches are welcomed!

(6) By Chris (crustyoz) on 2020-04-02 13:46:20 in reply to 5 [link] [source]

On first view, the use of a minus sign to indicate a button for displaying
less content was unexpected. Its function became apparent only when the plus
sign replaced it.

The accordian concept has been around for years and most versions use the
up pointing triangle to indicate "show less" and the down pointing triangle
to indicate "show more". Animating the button to rotate when clicked is a
nice but not essential feature.

(7) By Florian Balmer (florian.balmer) on 2020-04-05 14:45:53 in reply to 5 [link] [source]

I always liked your clean and simple UX style, to value functionality higher than a fancy look! Dating back long before Fossil, and lasting until present time, a lot of my web sites and wikis look like the SQLite web site. And Fossil uses the same approach, in most ways.

The following things bother me most about the Fossil UI:

Links to check-ins in unpredictable positions in the otherwise comfortable "Modern" timeline view (now mostly resolved by the timeline-tslink-info setting).
Links in unpredictable positions in the hamburger drop-down menu (depending on the width of the web browser window). Moreover, the menu open animation duration of 400 ms is beyond my limit not to feel interrupted. (The accordion uses a faster animation duration, which feels much better, also see Optimal duration for animating transitions and Response Times: The 3 Important Limits).

Anyway, I've made a few experiments with SVG icons for the accordion, similar to the "Copy Hash" icon. (Composing the SVG icons in my text editor was the most expensive part, maybe I should learn how to use image processing tools.)

Branch
Notes

(8) By Joel Dueck (joeld) on 2020-04-05 16:07:29 in reply to 7 [link] [source]

now mostly resolved by the timeline-tslink-info setting

What is this setting? I missed its introduction and it doesn’t seem to be documented.

(9) By Florian Balmer (florian.balmer) on 2020-04-05 17:03:15 in reply to 8 [link] [source]

It's on the /setup_timeline web page.

(12) By Gert (Wieseg) on 2020-09-16 09:24:52 in reply to 4.1 [link] [source]

Has worked perfectly in markup in fossil 2.10, also with images. Example (to try in 2.10) with summary text, that unfolds into details- text with attached image:

Level one (database root)

Here the database, you've logged in, is listed: 'XX'.

drawing

in fossil 2.12.1, now, the html tags are not rendered, but listed yellow as not renderable.

Can they be (re-)added into the allowed html? If rightly understood, this is a solution even without CSS or js to the first post of (drh)

Beeing not a programmer, I hope to help with this.

(13) By Richard Hipp (drh) on 2020-09-16 10:21:36 in reply to 12 [link] [source]

That's a new security mechanism. It's purpose is to prevent mischief in repos where anonymous passers-by on the internet can edit wiki.

You can disable it by going to the /Admin/Wiki pages and making sure the "Allow Unsafe HTML In Markdown" box contains the letter "w".

Or from a command-line, you type:

   fossil setting safe-html w -R $YOUR_REPOSITORY

(14) By anonymous on 2020-09-16 10:53:44 in reply to 13 [link] [source]

I think that Gert was asking to allow <details> and <summary> by default as purely static HTML5 tags that carry no exploitable behaviour with them.

(15) By Martin Gagnon (mgagnon) on 2020-09-16 11:10:21 in reply to 13 [link] [source]

That's a new security mechanism

About this new mechanism; Is it by design that a markdown document seen via the /doc/<VERSION>/... page bypass this security ?

(16) By Richard Hipp (drh) on 2020-09-16 12:05:46 in reply to 15 [link] [source]

The mechanism can be turned on and off separately for "/doc/VERSION/.." files (otherwise known as embedded documentation) using the "b" flag. So you can allow arbitrary HTML in Markdown for embedded documentation, but at the same time block it for Wiki. This is a reasonable thing to do if (for example) check-in privilege is restricted to trusted contributors but any anonymous hacker is allowed to edit wiki.

(17) By Martin Gagnon (mgagnon) on 2020-09-16 12:29:22 in reply to 16 [link] [source]

Ha ok, that makes sense.

(18) By Martin Gagnon (mgagnon) on 2020-09-17 03:25:31 in reply to 16 [link] [source]

What's about "/file?name=..." pages ? Should it use the "b" flag too ?

I have some Markdown document that are shown properly using the "/doc/VERSION/..." page, but appear with yellow tags when seen via "/file?name=..." page.

(10) By sean (jungleboogie) on 2020-04-08 19:54:37 in reply to 1.1 [link] [source]

Thanks Florian for the improvements! The UX of Fossil is turning out really nice. Thanks everyone for the improvements!

(11) By Florian Balmer (florian.balmer) on 2020-04-09 12:54:09 in reply to 10 [link] [source]

I'd like to point out that my contributions to the feature were just small.

I've just uploaded another change to reduce the size of the Javascript code a bit.

The feature can be also be tested with the links posted above.

@Developers and users of the Xekri skin: please let me know if you have a good idea how to fix the horizontal positions of the + and - icons for this skin.