Page MenuHomePhorge

Make the Remarkup Help Page Extensible
ClosedPublic

Authored by mturdus on Sun, Jun 23, 20:10.
Tags
None
Referenced Files
Unknown Object (File)
Thu, Jul 11, 00:36
Unknown Object (File)
Thu, Jul 11, 00:35
Unknown Object (File)
Wed, Jul 10, 22:28
Unknown Object (File)
Wed, Jul 10, 22:14
Unknown Object (File)
Wed, Jul 10, 22:00
Unknown Object (File)
Wed, Jul 10, 21:47
Unknown Object (File)
Wed, Jul 10, 11:03
Unknown Object (File)
Tue, Jul 9, 09:28
Tokens
"Yellow Medal" token, awarded by valerio.bozzolan."Yellow Medal" token, awarded by avivey.

Details

Summary

The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

  • /reference/remarkup/
  • /reference/cowsay/
  • /reference/figlet/

Closes T15401

Test Plan

Open the Phriction wiki editor and click on the Book (Remarkup Reference) icon in the toolbar and validate URL afterwards

Diff Detail

Repository
rP Phorge
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

mturdus requested review of this revision.Sun, Jun 23, 20:10

I don't understand what happened here?
I only had these files changed/added:

  • src/applications/reference/src/application/ReferenceApplication.php
  • src/applications/reference/src/controller/CowayReferenceController.php
  • src/applications/reference/src/controller/FigletReferenceController.php
  • src/applications/reference/src/controller/ReferenceController.php
  • src/applications/reference/src/controller/RemarkupReferenceController.php
  • src/infrastructure/markup/interface/RemarkupSyntaxDocumentationProvider.php
  • src/infrastructure/markup/interpreter/PhabricatorRemarkupCowsayBlockInterpreter.php
  • src/infrastructure/markup/interpreter/PhabricatorRemarkupFigletBlockInterpreter.php
  • src/view/form/control/PhabricatorRemarkupControl.php

I ran git pull and arc diff and it complained about 2 unit tests (some line with only blanks, which I think should have been untouched):

  • src/infrastructure/markup/remarkup/__tests__/remarkup/tick-block-multi-flavored-comment.txt
  • src/infrastructure/markup/remarkup/__tests__/remarkup/tick-block-multi-flavored.txt

I'm suprised it changed more than 1000 files by magic ?

It also collected lots of commits, since May 2023.

I think these commits have different hashes from the hashes in here - maybe you had a strange merge/rebase issue.

maybe try git rebase origin master to get rid of the duplicate commits? maybe rebase -i.

Make the Remarkup Help Page Extensible

Summary:
The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

  • /reference/remarkup/
  • /reference/cowsay/
  • /reference/figlet/

Closes T15401

Make the Remarkup Help Page Extensible

Summary:
The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

  • /reference/remarkup/
  • /reference/cowsay/
  • /reference/figlet/

Closes T15401

Looks good! I want to play with it locally before accepting.

Is there an "index" page?

src/applications/reference/src/controller/CowsayReferenceController.php
15

there's some magic to make phabricator also work, but the canonical form is phorge

34

I feel we need a joke here.

src/applications/reference/src/controller/ReferenceController.php
61

I did not add a real index page.
The remarkup reference acts a bit as index page as cowsay and figlet references are referenced in here as hyperlinks.

The document generation for cowsay and figlet, which consisted this phutil_get_library_root('phabricator')) code, was copied from PhabricatorRemarkupCowsayBlockInterpreter.php and PhabricatorRemarkupFigletBlockInterpreter.php.
These are btw not the only locations:

grep -r "phutil_get_library_root(.phabricator.))" | wc -l

Ok, this looks much better then what we have today, so yay.

One odd thing, I think the line-break logic is different between the Diviner and this rendering:

DivinerThis diff
image.png (134×718 px, 17 KB)
image.png (170×574 px, 20 KB)

Maybe a clue in https://we.phorge.it/source/phorge/browse/master/src/applications/diviner/controller/DivinerAtomController.php$633 ?

In my mind, we would also find all available rules, and each one will be able to create its own page (the simple ones will not, and will have basically the front page as it is now to handle them).

I think the next steps:

  • Mark this diff as "Refs" the task rather then "Closes"
  • Land this, with maybe some small changes
  • Later, do a revision where we add an index and automatically create a page for each instance of RemarkupSyntaxDocumentationProvider and/or RemarkupRule.

Re phutil_get_library_root: We didn't update most calls for because they weren't urgent (not user-facing), and we needed the magic anyway (for extensions), but when we touch them it's a good time to move them.

src/infrastructure/markup/interpreter/PhabricatorRemarkupFigletBlockInterpreter.php
84

This pops up as a new tab - can we make it target the same tab? T15161 should hold some tips.

src/applications/reference/src/controller/CowsayReferenceController.php
26

I see $ is more common in Phorge to match the end of the pattern instead of \z

Make the Remarkup Help Page Extensible

Summary

The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

/reference/remarkup/
/reference/cowsay/
/reference/figlet/

Refs T15401

Make the Remarkup Help Page Extensible

Summary

The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

/reference/remarkup/
/reference/cowsay/
/reference/figlet/

Refs T15401

src/applications/reference/src/controller/CowsayReferenceController.php
6

use = array() to create an array

src/applications/reference/src/controller/CowsayReferenceController.php
231

Make the Remarkup Help Page Extensible

Summary:
The Remarkup Help page is currently pointing to a HTML page on we.phorge.it.
Because of this it can not be customized/extended by custom extensions.
This diff allows you to implement a RemarkupSyntaxDocumentationProvider interface
to your custom class, which will implement a getDocumentation method.
This getDocumentation should return the custom help text in Remarkup format.
This diff also contains some extra help for the cowsay and figlet interpreters.
The local URLs for the local references are:

/reference/remarkup/
/reference/cowsay/
/reference/figlet/

Refs T15401

This revision is now accepted and ready to land.Wed, Jun 26, 18:51

I love this at unbelievable level, thanks all 🌈

Small possible minor things:

  1. I noticed the cowsay joke generator. It's lovely but it's a pity that most Remarkup is cached so I usually just see one while visiting /reference/remarkup/ - and I think this caching system should not be removed. Next step: maybe this may become a cowsay Motivator generator (http://phorge.localhost/home/menu/new/custom/motivator/)
  2. Probably the page /reference/figlet/ should add a small link back to the home Remarkup page + same for cowsay
  3. probably we can avoid the link «here» that is a bit not semantic, and we can have instead a link called «See the cowsay documentation» and same for figlet

Congrats to this patch.

  1. probably we can avoid the link «here» that is a bit not semantic, and we can have instead a link called «See the cowsay documentation» and same for figlet

Yeah I'd appreciate a followup because https://www.w3.org/TR/WCAG20-TECHS/F84.html or https://www.w3.org/QA/Tips/noClickHere :)