I'd love to have a Markdown editor on Windows to support fences so that I could actually create documents with embedded pikchr's in them. Notepad++ has the ability to syntax highlight Markdown, but not provide for fences (```). What file structure do people use to code .pikchr's?

What file structure do people use to code .pikchr's?

None at all. I compose the Pikchr there, then paste it into the resulting doc.

If I edit it afterward, and the change is both trivial and small, I just check it in directly, knowing what it'll look like with the changes.

Otherwise, I use the embedded doc ckout feature or the /wikiedit preview feature (Ctrl-Enter).

I compose the Pikchr there, then paste it into the resulting doc.

... Otherwise, I use the embedded doc ckout feature or the /wikiedit preview feature (Ctrl-Enter).

FWIW, same here - all three of those, depending on the context and scope.

(Note that pikchrshow also has Ctrl-Enter, thanks to the suggestion from Sean.)

Sigh... Another hidden tool chain...

Look guys, I cannot use Fossil because I my applications are built on Qt which Fossil does not support.

So please simplify the tool chain you are using. You are creating Pikchr svg using Pikchrshow, but you paste the input to it and copy the output? Some place you must have the original pikchr source to paste into Pichrshow. Is it in its own file?

Then when you copy the output, you must be pasting it into some other file. Is that an html file or what?

And then fossil does something with it to generate what? And what is that tool that generates the final output?

(And then you copy files for the website and paste them on the web server? How is that "in version control"?)

How many times in the various forums have OPs been chided for not showing the whole picture? Well I'm chiding you for not giving me the whole picture.

Please draw a pikchr to show the whole flow including all the files and programs used. It would like to use pikchr but I don't want to invent when I don’t have to.

Sigh... Another hidden tool chain...

Hidden? Pikchr was implemented primarily/initially for use in fossil-hosted documentation, and is only a few months old, so it's little surprise that fossil supports it and other apps and libraries, e.g. Qt, do not support it.

Look guys, I cannot use Fossil because I my applications are built on Qt which Fossil does not support.

It seems that you're overlooking the fact that pikchr itself can be embedded in any C or C++ application, independently of fossil. It's embeddable as-is in your Qt application.

So please simplify the tool chain you are using.

The toolchain we choose to use works fine for its initial intended purpose. For your purposes, pickhr can be embedded directly into your app and be 100% free of any fossil-related toolchain.

You are creating Pikchr svg using Pikchrshow, but you paste the input to it and copy the output? Some place you must have the original pikchr source to paste into Pichrshow. Is it in its own file?

It's wherever you want it to be. pikchrshow is a tool for experimenting and tinkering with pikchr, nor for managing one's personal library of pikchrs. However, if you want to store your pikchrs in local files and paste them into there for editing, that's fine, too (it supports drag and drop of text files for that very purpose).

And then fossil does something with it to generate what? And what is that tool that generates the final output?

The output is generated on the fly by the pikchr library, as called by the client application. In our case that's fossil (in several different contexts, only one of which is pikchrshow). In your case it's whatever application you embed pikchr in. You can also use the standalone pikchr CLI app which ships in pikchr's source tree.

(And then you copy files for the website and paste them on the web server? How is that "in version control"?)

You're apparently misunderstanding how pikchr works in fossil-embedded docs. The pikchrs are, by and large, not separate files. They are part of the documentation, embedded directly in the documentation. Fossil's own document processors process them when the documentation is rendered (on the fly when it's viewed). The SVGs, in our case, anyway, are never stored as SVGs.

How many times in the various forums have OPs been chided for not showing the whole picture? Well I'm chiding you for not giving me the whole picture.

pikchr's site includes tons of documentation. If you have concrete improvement suggestions for how to make it easier to understand, we're all ears. Nebulous accusations of us having secret handshakes, inadequate documentation, and chiding forum-goers (wha???) neither helps us improve the docs nor ingratiate us to your cause, though.

Please draw a pikchr to show the whole flow including all the files and programs used. It would like to use pikchr but I don't want to invent when I don’t have to.

A basic picture of that process is at the very top of this project's home page.

A more detailed picture and description of how to embed it in your own application is at /doc/trunk/doc/build.md (a link to which is on the project's home page). Aside from the documentation, the main() routine in this project's single C file is the definitive demonstration for how to make use of it from C/C++.

Dr. Hipp asked me to try out pikchr to see if it worked for me and to report any problems or ideas for improvement. I'm trying to use pikchr in my application documentation just like SQLite does.

I looked at your pikchr flow diagram and thought it was great. Except there is no sign of a file called "markdown.c" anywhere on the pikchr website. You say that "Fossil's own document processors process them". So can I have the document processor program (like I asked for), or is that a "secret" (your words)? Why is that code not on the pikchr website to facilitate usage?

there is no sign of a file called "markdown.c" anywhere on the pikchr website.

It's part of Fossil, used along with the parse tree to HTML renderer markdown_html.c.

I looked at your pikchr flow diagram and thought it was great. Except there is no sign of a file called "markdown.c" anywhere on the pikchr website. You say that "Fossil's own document processors process them". So can I have the document processor program (like I asked for), or is that a "secret" (your words)? Why is that code not on the pikchr website to facilitate usage?

markdown.c is part of fossil, and you don't need that file in order to use pikchr in your project. Richard likely offered it as a point of reference for how to filter out pikchr from a text stream and call into pikchr's API (it seems, though, that the pikchr-related bits are actually in markdown_html.c).

Management summary: there is no generic/project-agnostic standalone application to do what you're looking for. Your options, in short, are to either use the one tool which currently can do it (fossil) or write your own using the same pikchr API which fossil uses.

Details...

pikchr is independent of fossil. The integration of pikchr into markdown-based pages, such as this one, served by fossil is integral to fossil. If you want to integrate pikchr into documentation of your own, which is not served by fossil, you will have to write your own code to filter the documentation for pikchrs and/or process standalone pikchr files in batch mode which you can then integrate into your documentation using whatever approach works best for you. For example, a relatively simple approach would be to use IMG tags in your docs which refer to SVG files generated by your application or build process using either the pikchr C API or the standalone pikchr CLI tool (both of which are embedded in the standalone pikchr.c).

There is no generic standalone program which doing that. Fossil does it, in the context of documentation files it serves, because it's one of fossil's builtin features (its internal "document processor" bits), not because it's part of some secret toolchain. Since you "can't use fossil," if you want to use pikchr then you'll have to integrate it into your application and/or docs similarly to how fossil has done so.

If you'll look at the source code for this post using the "source" link near the top of it, you'll see the pikchr source code for this image, wrapped up in a markdown-specific "code fence" block:

bgcolor = 0x1d2021
circle

The SVG form of that is rendered by pikchr, via fossil, when fossil serves the rendered form of this forum post. That's the "fossil document processor" in action (it's an internal feature, not a separate piece of software, and it's doing far, far more than just replacing that pikchr block). The exact same applies to all documentation served directly by fossil. Whether or not the specific docs you're referring to in sqlite are handled that way or whether they are pre-processed using the pikchr CLI app (or equivalent), i don't know. You'll have to point us to examples before we can answer that. If, for example, you mean files like:

https://sqlite.org/lang.html

Those are static HTML files which are built by an sqlite-specific build process which is beyond my ken but is available in full at:

https://www.sqlite.org/docsrc

That particular file's source code is a mix of HTML and embedded TCL:

https://sqlite.org/docsrc/finfo?name=pages/lang.in

and the first SVG on that page is generated (in batch mode by the build process) from this file:

https://sqlite.org/docsrc/finfo/art/syntax/sql-stmt-list.pikchr

That build process is very much tailored specifically to sqlite's needs and is likely not a good fit for you as-is, but may provide a starting point or study reference. Notice that that tree includes its own embedded copy of pikchr.c:

https://sqlite.org/docsrc/finfo?name=search/pikchr.c

Your application cannot simply use fossil's markdown processor as-is because that one is full of fossil-isms like processing of fossil content links. You application can use the single-function interface of pikchr.c to process any pikchr content you have (just like fossil's internal doc processors do). If you have a Qt-powered markdown processor and the option of filtering the markdown files to pick out the pikchr elements, you can filter out those pikchr sources, run them through pikchr.c's API, and replace them with the generated SVGs (that's exactly what fossil internally does). However...

If you're looking for generic/project-agnostic code which filters markdown looking for/replacing pikchr blocks, you're out of luck: you're going to have to write that yourself. Fossil's version of that won't help you other than as a reference for study in implementing your own take on it.

Edit: my response overlapped responses from Warren and Richard. Be sure to see Richard's note about AsciiDoc, which apparently offers embedded pikchr support.

I can share some extra information on how the asciidoc support works. What I use myself is the following combination:

• The community edition of IntelliJ IDEA as base editor. This is a Java IDE at heart, but nowadays it has a 'LightEdit' mode that allows you to edit files without actually creating a project. I haven't used this myself though so no idea how well it works.
• The Asciidoctor plugin for IntelliJ.
• The Asciidoctor processor and the Asciidoctor Diagram extension. These are bundled with the IntelliJ plugin.

This setup gives you a GUI editor with live preview where you can embed fenced pikchr diagrams in the rest of the content. The asciidoc syntax is similar to markdown:

= Heading 1

Some text

[pikchr]
----
your Pikchr diagram goes here
----

Some more text

You can use the asciidoctor toolchain via the CLI as well of course to generate HTML, PDF, ePUB, ... that contains the rendered version of the Pikchr diagrams.

FWIW, the fossil document processor is available as a CLI subcomand, ready for use in e.g. a Makefile :

fossil test-markdown-render yourfile.md >yourfile.html

bgcolor = 0x1d2021
right
file "yourfile.md" fit
arrow
box "fossil test-markdown-render" fit
arrow
file "yourfile.html" fit

-- 
Regards,
Kees Nuyt

This is very close to what I was looking for, except the html includes the pikchr code wrapped in

<pre class='pikchr-src'>

In my implementation, I strip all that with an awk strip script, which also adds id attributes to <h[digit]> header tags, so they become fragment identifiers that can be referenced in <a href=#fragment_id">...</a> links.

The awk script:

## strip.awk
## Add anchors to <hN>title</hN>
## Drop  <pre class='pikchr-src'>...</pre>
#
/^<pre class='pikchr-src'>/,/^<\/pre>/{
  next
}
{
  sub(/ align="left"/," style=\"text-align:left;\"")
}
/^<h[[:digit:]]>.*<\/h[[:digit:]]>$/{
  h=substr($0,5,length($0)-9)
  a=tolower(h)
  gsub(/[[:blank:]]+/,"",a);
  print substr($0,1,3) " id='" a "'>" h substr($0,length($0)-4)
  next
}
{
  print
}

And so the process becomes:

fossil test-markdown-render yourfile.md | gawk -f s/strip.awk >yourfile.html

-- 
Regards

After thinking about it, I solved the <pre...> problem a different way:

<style type="text/css" rel="stylesheet">
pre.pikchr-src { display: none; }
</style>

I cannot use Fossil because I my applications are built on Qt which Fossil does not support.

That's probably a topic for the Fossil forum, rather than here, but could you please explain that, either here or there? Fossil will store a Qt application's source code just fine, and a Qt application can call Fossil just fine, so what does it mean for Fossil to "support" Qt?

I searched the Fossil forum for "Qt" and find no complaints about it there.

Stephan said on 11/29 Qt question that there was no interface for fossil to Qt. Was he mistaken?

Stephan said on 11/29 Qt question that there was no interface for fossil to Qt. Was he mistaken?

There is no library interface for fossil, and therefore no API for Qt (or any other toolkit) to interact with other than by calling the fossil binary and parsing its output. Fossil's JSON API can make certain such use cases feasible, but fossil's output is otherwise not to be considered "stable" for such purposes, in that it may well change in any given fossil version.

I suppose the answer to that question depends on the extent to which you believe Qt is an operating system and thus needs to provide API abstractions for everything. I see that there's a Qt Bluetooth module these days, for instance. 🙄

Up-thread, someone suggested using fossil test-markdown-render: does calling QProcess.start() on that command constitute an "interface to Fossil"?

If what you're actually asking is a C++ API for Fossil, having nothing at all to do with Qt, then I direct your attention to this active thread on the Fossil forum.

Wrong direction, Warren. I write applications using Qt as my interface to everything. It has built-in capability for version control of my application source code: checkout, checkin, commit,... I selected 'git' as my underlying VC. I thought I might try Fossil as my version control, but Qt and Fossil don't talk. You're right that I could write application code to interface to fossil but that's something altogether different.

Then I think you mean Qt Creator, not Qt proper.

Yep, I mean Qt Creator.

... I thought I might try Fossil as my version control, but Qt and Fossil don't talk.

There's Fossil plugin for QtCreator.

It's been available for quite a few years. Recently the QtProject added it to their GitHub workflow, so that it's also built automatically. The plugin binaries are in the Releases section.

You definitely need a Markdown-to-HTML converter that supports both fences and Pikchr. Right now, that choice is limited to Fossil and AsciiDoc, as far as I know. Hopefully, other Markdown rendering engines will pick up support for Pikchr in the future. (You should encourage them!)

For on-line editing of Pikchr scripts, you have multiple options. Here are a couple:

• https://pikchr.org/home/pikchrshow
• https://jakethaw.com/pikchr_webassembly_demo/

Aside: While searching for that second link, I noticed that there are multiple GitHub repositories now associated with Pikchr!

If you have a generic Markdown renderer that support fences, but not Pikchr, you might be able to combine that with Jake Thaw's wasm-pikchr to get it to render correctly on-device. If you try that and get it working, please report back.

What I Use To Develop Pikchr Scripts

I use an ordinary text editor to write the script. For testing I then run:

pikchr myscript.pikchr >test.html

Then I view test.html in a web-browser. I fix problems and repeat. I keep doing this until the pikchr looks right. No special tooling (other than pikchr itself) required.

Perhaps a round-about way to preview your Markdown files which include Pikchr fence-blocks is to leverage Fossil's wiki command line functionality.

The example workflow for a file 'test-pikchr.md':

fossil init test.fossil
fossil open test.fossil -f
fossil wiki create test-pikchr -M markdown test-pikchr.md
fossil wiki export -h test-pikchr > test-pikchr.html
fossil close -f
rm test.fossil

Would produce the 'test-pikchr.html' with the rendered Markdown. Just keep in mind the fenced-block should be marked on opening as ```pikchr to be properly rendered.

Not the most efficient way, but this could be automated in your documentation workflow.

Along the same line, there is also fossil test-markdown-render:

https://fossil-scm.org/home/help?cmd=test-markdown-render

Handy for causual use.

Along the same line, there is also fossil test-markdown-render:

With the caveat that no fossil commands named test-* are supported. They may disappear or be changed in incompatible ways with any given fossil checkin. They exist solely to support testing of fossil.