Are there any alternative help formats to SMCL? Maybe markdown or HTML?

[John Eiler]

I'm trying to write a help file for a command I just wrote and wondering if I have any options besides SMCL? I'd be open to any commonly used standards such as markdown or HTML.

I'm pretty sure the answer is going to be that I have to bungle my way through the intricacies of SMCL, but I couldn't find any definitive answer one way or the other so I thought I'd ask.

Also wondering if there are any converters from HTML or markdown to SMCL? There seem to be converters in the other direction, but that doesn't save me from writing SMCL here.

[Sergiy Radyakin]

An SMCL file is essentially a text file. While you can, you don't have to use the smcl-specific markup in the text.

Many users would be quite happy with the documentation in PDF. Then just have a minimalistic help file with a single link to the accompanying PDF. That much, I am sure you will accomplish in no time. Then just make sure your PDF is included into the package for the distribution.

At least several of my commands have the same approach, but lead not to accompanying PDF file, but to a companion site, which can be updated with a higher frequency than the command code. There are advantages and disadvantages to this approach, but it seems that StataCorp is also using the same route with some advanced topics (like Java and Python).

Whichever way you go, you will find plenty of help from the list members regarding particular challenges in the SMCL.

[Nick Cox]

As Sergiy Radyakin explains, your can write your own documentation in whatever format you like. How and indeed whether users can read it remains a question.

But why did StataCorp invent and introduce SMCL, recursively meaning SMCL Makes Cooler Logs?

The essence is that Stata must be able to interpret single statements including SMCL directives on the fly, often without reference to earlier or later mark-up in a document. That's quite unlike HTML in particular.

[Mike Lacy]

I have found writing help files with SMCL challenging, too. I generally find a short help file that someone else wrote (e.g., Nick) and edit it for my own command. That helps a lot and teaches me something. There's also a user-written command available at -ssc- called -makehlp-. I have not seriously used it, but my recollection is that it was useful.

[Nick Cox]

It helps to have started using SMCL when it was introduced -- and was simpler because it contained fewer directives. Thus I doubt that I use very much of SMCL at all. As Mike Lacy kindly points out I too tend to write a new help file by hacking at a copy of an existing help file.

[Sergiy Radyakin]

Same here. SMCL is completely impassable from scratch, and rather unpredictable from appearance: empty lines, long lines, tabulation, spacing and other seemingly innocent things may completely transform the way how the final text appears in the viewer.

I feel that if the HTML 1.0 was implemented in the viewer that would have been more than sufficient for all the documentation and logging needs.

A simple set of tags: <TITLE><H1>...<H6><P><B><I><U><TT><FONT color=><A><IMG><OL><UL><LI><HR><BR><PRE> is something that one can learn in 15 minutes and keep on using for the rest of the life. The tables, I believe, were not part of the original definition, but would have been useful to support too:<TABLE><TH><TR><TD>.

Support of HTML in output window would have opened a way for inclusion of formulas, tables and graphs directly into the output window, rather than separate outputs, (notebook style approach). Kind of what [a competing product] is doing it:

[John Eiler]

OK, thanks Sergiy, Nick, and MIke! Making a simple help file focused on syntax and then doing the rest of it via a link or PDF sounds like a good and practical strategy. Also kind of comforting to see that everyone here has the same attitude about SMCL as me. ;-)

[Nick Cox]

I like SMCL, and i don't want anyone inferring otherwise.

[John Eiler]

I like SMCL, and i don't want anyone inferring otherwise.

Sorry if I implied this to you, Nick, and obviously you are not the more typical Stata user with whom I was attempting to express solidarity. ;-)

FWIW, I don't have a particular problem with or dislike of SMCL and I can imagine that it made a lot of sense for Statacorp to create SMCL at the time (before HTML or markdown existed, probably?) The "issue", if we call it that, is just that there are now lots of alternatives like HTML that aren't necessarily better in a vacuum, but that are better in the sense that they are widely used, widely understood, and you can easily write and view HTML code in a WYSIWYG editor without having to learn HTML at all.

As was pointed out to me in this thread, the cost of having to write a SMCL help file is probably not that high, but it's still higher than it would be if you could, say, write it in HTML or markdown.

[Nick Cox]

StataCorp have used TeX or LaTeX almost since the beginning for documentation and HTML on the website. That's two systems already, but also they needed SMCL for themselves. The decision to devise a new language hinges on the need to interpret single lines of text containing SMCL directives without the context of what comes earlier or later. When Stata writes to a log file that is in SMCL, for example, it writes lines one at a time just as it does within the Results window. That's not the way that HTML is interpreted.

This has several helpful side-effects, for example, it can be useful to use type to show a remote help file.

As I understand it there is no obvious reason why Stata help files could not be written in HTML, and that wouldn't depend on using a browser to read those help files. That wasn't the decision.

I have written some HTML files but I am a beginner. I can guess that anyone who knows HTML well would find any need to learn SMCL too a bit irritating but it takes a few minutes to get started.

[John Eiler]

As I understand it there is no obvious reason why Stata help files could not be written in HTML

Yeah, that was the only reason I bothered to ask, even though I was pretty sure the answer would be no.

I have written some HTML files but I am a beginne.

Actually, I think the advantage of HTML would be that folks could write in almost any editor and merely save as HTML. I actually did hand code web pages once, but that was a really long time ago, and I don't have much more desire to do that than to hand code SMCL.

[Nick Cox]

Now I don't understand. I gather than I can format a document in MS Word (for example) and save as HTML. And for a while I could make use of something that translated TeX to HTML, and not very well.

But I have no idea how any text editor will be able to know or guess what mark-up should be applied to a document unless I insert that myself. Please explain.

[John Eiler]

I'm not sure I understand the question... I just meant that if your editor has "save as HTML", then that will put HTML tags into the document. It's the "save as HTML" command that tells the editor what markups to apply. E.g. you type "regular text bold text" into MS Word and when you save as HTML it becomes "regular text <b>bold text</b>" without you needing to know even basic HTML or worrying about typos in the HTML tags.

[Stephen Jenkins]

Late to the party, but I like to support the views expressed by Mike Lacy in #4. In particular, I would recommed makehlp on SSC (by Adrian Mander) as way of automating production of help-files from your ado-file. It's worked very well for me on the several occasions I've used it. It's straightforward to edit the resulting file (in the Stata do-file editor too). Otherwise, starting from an existing help file is the way to go, as Nick Cox suggested.

[I have zero knowledge of HTML. I find SMCL hard to remember, but I typically don't have to remember very much, or learn much, given what I say in the first paragraph. Stata's help is good for me.]

[Nick Cox]

. I just meant that if your editor has "save as HTML", then that will put HTML tags into the document.

OK, but mark-up of some kind has to be supplied somehow, I think. No editor will look at bare text and decide on mark-up, so far as I know.