[John Eiler]

Ah, I wasn't sure exactly what makehlp did, but that looks helpful. Here's a link to some slides that seems to explain it pretty well:

https://www.stata.com/meeting/uk18/s...k18_Mander.pdf

And, sorry, Nick, but here's the lead quote on that slide. ;-)

Richard Williams posted on statalist (11 Apr 2008) ”Writing programs is kind of fun, but writing help files is pure drudgery”

[John Eiler]

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.

Of course not. You apply an "implicit" markup by double clicking the word and then clicking the "B" button to bold it. The difference between the various methods is basically if you are formatting with your mouse (WYSIWYG) vs remembering actual markup commands, whether in a widely used standard like HTML or a less widely used standard like SMCL.

But the "makehlp" command seems to be a partial third way, and sounds very helpful although I personally haven't tried it yet.

[John Eiler]

Update: just tried "makehlp" and it's very nice! With almost no effort you get a barebones help file template, with the syntax automatically imported from the ado file.

[Nick Cox]

Thanks for the detail in #16. In an editor you don't name you can make things bold by double-clicking and clicking. And perhaps it allows several other such tricks.

We should agree that there are several ways of adding mark-up. The one you know best is least painful. The one you've never heard of has all sorts of arbitrary details that make sense if and when you've learned them.

"Of course", as you say, writing help files is drudgery. I didn't say otherwise. Given that you have to do it to be taken seriously, SMCL grows on you.

[John Eiler]

We should agree that there are several ways of adding mark-up. The one you know best is least painful. The one you've never heard of has all sorts of arbitrary details that make sense if and when you've learned them.

Yes! I think we can all agree on this one. ;-)

[Sergiy Radyakin]

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

Isn't this what we call syntax highlighting?

Syntax highlighting is a feature of text editors that are used for programming, scripting, or markup languages, such as HTML. The feature displays text, especially source code, in different colors and fonts according to the category of terms.

For trivial help files that document the syntax of a command, I don't think there is a mandatory requirement to format every option as such. It is possible to inspect the syntax, and deduce from it that, e.g. topval() is an option and highlight topval with option style (e.g. italics) in the description. Kind of what makehlp is doing to generate the template, but in real-time processing of the help file.

But not all help files document a particular syntax, it could be a general description of the method, requirements for input data, or interpretation of the results. In which case, indeed, it is the author's responsibility to mark the logical elements of text.

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.

SMCL lines are still dependent on the earlier lines (it does have the hyperlink feature, the interpretation of lines depend on whether {smcl} directive was mentioned earlier in the file, line/paragraph modes, etc). But the question is why is the problem setting relevant for help files? Why documentation for PhotoShop, Chrome, and other software does not require interpretation of lines separately, but for Stata's documentation this is needed or desirable?

SMCL is a wonderful language for machine-generated output, where it is relatively easy to configure your code to produce the formatting tags as necessary to produce beautiful log file. But for writing manually it is, imho, a flop.

Summarizing my experience and some of the points made by others:

	SMCL	HTML	PDF	TeX/LaTeX
Language	Unique, proprietary	Common, used in multiple systems	non-text, binary, requires specialized tools	Specialized,but well-established
Source of documentation, reference materials	Single source	Multiple alternative sources of reference	multiple alternatives	multiple alternatives
Tolerance for errors/sloppiness	Low	High	No tolerance, or very low	Low
Tools to validate the file	None, except to review it with your own eyes	Multiple tools to validate and point at common errors, such as tags not closed, invalid tags, or tags parameters or values. https://validator.w3.org/ https://www.freeformatter.com/html-validator.html	Exist	Exist, errors are hinted at during compilation.
WYSIWYG tools availability	No WYSIWYG	WYSIWYG editing tools available https://www.guru99.com/best-wysiwyg-html-editor.html	Most authoring tools will give you some idea of what the final layout will be.	Limited, but present https://en.wikipedia.org/wiki/ Comparison_of_TeX_editors
Platform portability	High, appears same or virtually the same on different platforms	Moderate, often appears differently (fonts, styles) on different platforms or in different browsers	Very high. The files appear identical.	??? Not clear. My experience is: rather bad portability.
Security	Secure (no known cases), though still can format your hard drive if you click on a malicious link.	May be perceived as insecure if JavaScript or some other techniques are permitted/used in the files. https://html5sec.org/	Considered to be relatively high with modern viewers, but is still questionnable: https://security.stackexchange.com/q...ontain-a-virus	??? Not clear.
Multimedia content	Possibility to include links, integrate executable statements into the file	Possibility to include links, graphics, videos, forms, other content in the file.	Possibility to include links, graphics, forms.	May contain links, graphics
Conversion	from SMCL to text, to HTML, to PDF from do/ado to SMCL -makehlp-	from HTML to DOC, PDF from DOC, PDF to HTML https://www.pdfonline.com/convert-pd...l/default.aspx	HTML, DOC, SMCL -> PDF PDF -> HTML, DOC	TeX->PDF HTML, DOC ->TeX http://htmltolatex.sourceforge.net/ https://www.docx2latex.com/
Viewing requirements	can be viewed by Stata users only (requires paid software) needs to be converted to other formats for proliferation to outside-of-Stata world.	Can be viewed by most users for free (most operating systems include a browser of some sort, capable of displaying the content at the formatting level, free alternatives exist).	Can be viewed by most users for free (most operating systems include a PDF viewer of some sort, often free and with numerous alternatives).	LaTeX files need to be compiled to PDF or PS files before they can be viewed. Compilation may be done by the author, not necessarily the reader. Free compilers exist, though are probably beyond what the most users would want to install just to quickly read some text. https://miktex.org/
Possible to produce from Stata's code	YES write as text file, or record as log file	YES write as text file	YES putpdf	YES write as text file

Please treat all links here as examples/illustrations only, not as recommendations.

[Sven-Kristjan Bormann]

I am maybe a bit late to the party, but help files can be written in Markdown and then translated in SMCL with the help of the markdoc package https://github.com/haghish/markdoc https://www.stata-journal.com/articl...article=pr0064.
With this package, you can write the documentation for your command in the head of your command as a comment for Stata. The markdoc-command then generates the help file for you.
I have not used this package before but, I consider it using it next time for my help files.