a _fossil markdown_ command
(1) By anonymous on 2023-02-05 09:00:37 [link] [source]
Working on adding a pikchr block to a README.md, I realized that giving fossil one of the following commands would be helpful for someone developing documentation that's checked into the source tree:
- fossil markdown -- generate the HTML from a file.
- fossil pikchr -- generate the SVG from a file's code blocks.
I ended up downloading pikchr.c, compiling it and doing the edit, compile, view iterations with --svg-only argument to pikchr. Having fossil support this directly would be helpful.
Issues I don't have answers for:
- How do you prevent the command from leaving detritus on the filesystem?
- If the fossil pikchr option is taken, what do you do with multiple pikchr blocks in the same file?
(2) By Stephan Beal (stephan) on 2023-02-05 11:44:17 in reply to 1 [source]
fossil pikchr -- generate the SVG from a file's code blocks.
Fossil has a pikchr command but it reads pikchr input, not arbitrary text.
fossil markdown -- generate the HTML from a file.
This also exists but under a different name: /help?cmd=test-markdown-render
(4) By anonymous on 2023-02-05 16:03:24 in reply to 2 [link] [source]
TIL -- that a fossil help -a exists. I don't know how I've never seen that before. Note: the fossil test-markdown-render command needs listing in the output of fossil help -a.
These are exactly what I wanted. Apologies I missed the -a option.
(5) By Stephan Beal (stephan) on 2023-02-05 16:11:08 in reply to 4 [link] [source]
Note: the fossil test-markdown-render command needs listing in the output of fossil help -a.
Nope - all commands which start with "test-" are considered testing/internal-use commands are not considered part of the canonical command set. They are only listed with the -t/--test flag.
Every now and then a test command get "upgraded" to a "real" command. If you can make a compelling case for doing so with this command, it might be considered, but note that fossil is intended to be an SCM, not a do-everything tool for everyone's particular way of working. It's far more convenient to use fossil's /doc/ckout/myfile.md approach to editing markdown files than it is to render the markdown to HTML files and view them some other way:
fossil ui -page /doc/ckout/myfile.md
then simply tap reload in the browser after each edit.
(6) By Martin Gagnon (mgagnon) on 2023-02-05 16:11:38 in reply to 4 [link] [source]
fossil help help also help ;-)
(3) By Warren Young (wyoung) on 2023-02-05 14:26:09 in reply to 1 [link] [source]
Working on adding a pikchr block to a README.md
While you likely have a favorite text editor that's far more powerful than a web browser's <textarea>, being able to press Shift-Enter in a /fileedit tab in order to toggle back and forth between the rendered version of a document and the editor cuts the edit-test-fix-extend cycle time considerably.
Enable it1 in the Fossil UI settings for *.md, then use /dir to browse to your README.md file, where you can then click the Edit button in the second-level menu bar to pull it up into an in-browser text editor.
Once you've got the diagram working properly, you can go back to your terminal window, say fossil up to get the edits and continue working on the prose in your favorite text editor.
what do you do with multiple pikchr blocks in the same file?
When a document gets long enough that I have to page down vertically multiple times to see the changes in my diagram,2 I copy the Pikchr code to the clipboard, then paste it into a /pikchrshow tab and work on it there. Only once it's finished do I copy it back into the document and render it in-place to see how it all flows together.