Hello everyone
I have this dream of writing things in markdown (which is the format I write all my text in so that it can be easily converted to html or pdf using pandoc) and being able to convert to schelp from a markdown document. Before I dive into this rabbithole and try to devise a way myself, has anyone else done this before? For me at least this would make the process of writing help files (especially guides and tutorials) a bit less painful.
markdown is inherently less expressive than schelp and most other documentation formats like javadoc and restructured text. to provide the full feature set of schelp syntax, you’d need to create your own special commands for instance methods, special notes, warnings, footnotes, etc. etc., at which point you’d basically be reinventing the documentation format itself. markdown is just simply not designed or equipped for this purpose. schelp is not a difficult format to learn and is already convertible to html, i’d recommend sticking with that.
if all you need is to convert something simple in markdown to schelp, i don’t know of any solutions but a python script could probably do the job.
brian
You might laugh at me, but I still write my help originally with the old WYSIWYG SC help system (html on mac, you’d need 3.5 on an old mac I think), where you can take existing help files as templates. Then I’m quite fast in converting them to schelp with copy and paste (from old help and existing schelp files) and just a few core commands.
I got part of the way toward an Emacs org-mode exporter to scdoc syntax, but I never finished it (for lack of time).
Org-mode is more expressive than markdown and supports many varieties of tags and properties. I think it could be made to reflect scdoc metadata.
If interested, I could try to track it down on a backup drive somewhere.
hjh
Although I like the format, I hate to have to edit help in a different file, because it’s more work, harder to keep track and prone to be left behind thus making it inconsistent. I like using comments for documenting help files, like with Doxygen. I’m seriously considering on making a Doxygen-to-SCHelpSystem converter, or something similar. Has anybody started working on it already? I’d be happy to join.
Actually, I like the idea of keeping code and docs together (how long before someone brings up literate programming? 
Actually I’m not a huge fan of true literate programming, but that’s just me I guess).
If it 's not possible/practical to introduce a doxygen-like system then some key combination to immediately switch from class to doc and vice versa (adding non-existing files on-the-fly) in combination with a live preview pane (or wysiwyg mode) for schelp docs would be nice to have as well.
The scdoc system has a true parser, which should mean that there’s a strong relationship between the scdoc documents and, for example, the rendered HTML. If anyone is invested in improving usability of scdoc, a REALLY good place to start would be to embed file location info in the HTML. This would allow you to do in-browser editing via editable and then apply those changes back to the original scdoc. This doesn’t solve the problem of writing an scdoc from scratch, or making structural changes, but it makes it very easy to e.g. pre-populate a template doc (this functionality already exists), and then do all the copy editing in the browser. Before any attempts are made to introduce new layers/frameworks/tooling to the doc system, I think this sort of thing should be investigated - I think technically this is NOT very difficult work, but has a really high user benefit.
As a reminder also - these discussions about the docs system come up every year or so - I think with good reason, as there are some real issues here. But just so it’s not in a vacuum: basically all of these concerns and proposals (e.g. doxygen, literate programming, wysiwyg) were discussed at length when the scdoc system was created. I don’t agree with every detail, but there were strong reasons for all of the decisions that were made. It’s worth digging through the sc-dev / sc-users for these convos if you’re interested in how we ended up with the system we have. I’ll post ML archive links if i can find some (or maybe someone else has an idea?)
bit of a shameless plug, but recently scvim gained support for schelp syntax. that update is not yet part of the mainline SC repo, but if you clone the repo separately (or update it to the latest master, if you have cloned the main SC repo and have it as a submodule), you can get it.