I am reposting Sergiy's last comment at the bottom since it did not
make it to the archive.
I thought about the translator thing, and this should not be
difficult. I also see that the Stata Corp is silent on this issue. My
guess is that it has not been done because the translator will not
work for the same reason that the Stata is not capable of displaying
high resolution images. It looks like something out of 1980s, except
it comes in color. Think Atari or Commodore 64.
It doesn't matter if it's smcl or ascii or whatever. It will always
look bad on Stata display window. This is one of reasons I never
bothered to display tables there. Even the browser has a better
resolution. I'm guessing a higher resolution will slow it down because
it's hard to imagine they could not farm this out. You'd think at
least the viewer window would have a better resoultion than this. But
if they did that, it would make the main window look terrible by
comparison.
If you look at the official help files they avoid writing too much and
use small paragraphs only. Users don't know this, and they cram too
much, and it starts looking hideous (no c-letter word here). This is
how people get sucked into putting hours and hours of work with
nothing to show for it. Having a translator is not going to prevent
this. People who don't know smcl can work off a smcl template. It's
the bad results after hours of work that drive you crazy.
I would say that .pdf file is the most realistic option if people want
something that looks decent and can in fact can be made to look
decent.
Roy
> November 22, 2009
> Dear All,
> Thank you very much for your feedback! This is a not-so-brief summary
> of the major points that came as a response to my inquiry “TeX
> template for PDF help files” and my additional thoughts. I am not even
> trying to be objective here; I try to mention the contributors and I
> hope I understood all the suggestions correctly.
> From the discussion in the list I’ve understood so far:
> 1. At least some statalist members share my view that SMCL is not a
> very convenient format to create documentation for user-written Stata
> commands.
> 2. While I only wanted a TeX template for the help files, it became
> clear from the discussion that PDF is not an obvious choice, thus
> moving the discussion to a new level. A number of alternative formats
> for help files exist, among most frequently mentioned are PDF and
> HTML; Windows users could through in several Microsoft’s formats for
> help files.
> 3. There is no consensus regarding how the help file in these formats
> should be produced: for PDF the document could be generated by Word or
> LaTeX, (and from other software if needed). Perhaps both templates can
> exist in parallel and each contributor could select the one he/she
> likes more.
> 4. There is no consensus on what software is widespread enough to be
> considered essential base tool to rely on. Microsoft Word and LaTeX
> are mentioned as candidates. Word is not free, LaTeX may be more
> difficult to learn/operate or even install.
> 5. SMCL provides the following possibilities unmatched by any
> alternative format:
> a. possibility to include executable examples right into the document
> with “click here to run” links;
> b. possibility to be called from the command line with the standard
> -help- command;
> c. possibility to refer to standard PDFs ({manlink} tag). (I think we
> can still link to the Stata help files located in the internet,
> though).
> 6. I do not really care about examples. For the reason that they will
> create some output, which can just be embedded into the PDF document.
> It was not possible for graphic commands in Stata simply because the
> output could not be inserted into the document, but now I don’t see
> any additional benefit to the “runnability” of the examples.
> 7. There was not enough attention to the security implications of this
> transition. In particular, HTML files can have scripts embedded into
> them, and PDF and DOC files can have their macros. While this does not
> sound like a big threat, we might be opening the Pandora box here. I
> think providing source TeX document to Kit and centralized compilation
> of help files in PDF could be a way to overcome this. It is less clear
> how to guarantee security for users installing packages not from SSC
> but from elsewhere.
> 8. Graphics and formulas cannot be embedded into SMCL help files,
> which is quite frustrating, in my opinion. Particularly for graphic
> commands, a picture is definitely worth a 1000 of words (and this
> limitation is successfully addressed in the wonderful Mitchell’s book
> on Stata graphics: show which graphic option does what, don’t tell).
> 9. File size also hasn’t been mentioned as a concern, but I guess we
> may need to factor this in, as some PDFs tend to be notoriously huge,
> when done without optimization or tweaking the defaults of the
> software used for conversion. Larger help files will put more stress
> on storage and traffic. This mainly concerns Kit, since he has to deal
> with thousands of packages, but also for users who have plenty of
> packages.
> 10. Roy Wada has created a Word document and it’s PDF counterpart to
> illustrate how the user-written commands may be documented in PDF. The
> document itself looks nice and (I am sure) will be comfortably
> accepted by the users. However this document is strictly speaking not
> a template: it defines neither Word styles to standardize the look of
> the elements, nor it defines the sections firmly. Microsoft provides a
> number of templates on their website
> (http://office.microsoft.com/en-us/templates/). Templates for Word
> must be saved as a .dot or .dotx files, so that Word automatically
> recognizes them as templates and properly protects them. Templates may
> use macros to interact with the user, e.g. in the form of a wizard and
> request some information to be used to generate the document. Defining
> (and using) styles is essential in my view, because it will allow
> automatic updating of formatting in the help files in the future, as
> well as proper merging of help files in the larger documents.
> 11. Roy provided a code of -phelp- command to allow users to call the
> help files in PDF format from the command line. I would probably
> prefer another approach (also mentioned by David Airey), where
> packages still come with an .sthlp file, which is a stub, and all it
> contains is a link saying: “This package is documented in PDF format.
> Click here to open this PDF.” In this case the users will not have to
> install any additional commands before they can enjoy viewing the PDF
> help files. I think renaming the .sthlp file and changing the PDF name
> inside it is a task of sufficiently low skill and effort. This
> approach also has the compatibility benefit – the stub can be expanded
> to contain the full text of the help for users that for some reason
> can’t view PDFs, are afraid to click links, or just want a quick
> reminder and don’t want to wait for the PDF to load.
> 12. Using specialized programs to produce help files in multiple
> formats (like Docutiles) is a nice idea (Phil Schumm), but I doubt it
> will fly. Unless it is my business strategy to provide people with
> help files in every format (like it is StatCorp’s business strategy
> that Stata works on every platform), I will not invest into installing
> and learning a new documenting system that will produce such output. I
> think it is safe to assume that most .ado files are by-products of
> programming to fulfill other major tasks, which became extracted from
> the project, generalized, documented and shared with other users. In
> contrast to StataCorp’s programmers, we do not develop them for
> profit, so demands of the market are irrelevant. However this is what
> we are determining now, - how the documentation for the next
> generation of ado files is expected to look like. The expectation is
> that it should be 1) more comfortable for the users (more features and
> convenience), and 2) more comfortable for developers (less time and
> effort to produce it).
> 13. Let’s not point with fingers, but in some organizations
> suggestions to install a “not-so-well-known” software “somewhere from
> the internet” is considered equivalent to a request for permission to
> have a loaded AK47 on the desk. So any marginal software (though
> however useful and otherwise wonderful) has absolutely no chance to
> even get installed.
> 14. In general I would strongly oppose installing anything beyond what
> is reasonable to expect is already installed. Perhaps one file
> (whether a .dot for Word, or .sty for TeX) with clear instructions how
> to use it (not some “put it somewhere where TeX can find it…”, which
> probably knocks many inexperienced users).
> 15. Another idea was voiced and discussed was to create a wizard or a
> form in Stata that would request from the users the information
> corresponding to the sections of the help file, and then generate an
> SMCL output automatically, as well as in PDF or other format
> convertible to PDF. This would probably not work, simply because we
> expect so much from a form, e.g. as a non-native speaker I prefer to
> have the spell-checker on all the time to correct (or at least to see)
> my errors immediately – something we will not get in a Stata form.
> 16. StataCorp’s involvement into this process could greatly simplify
> the matter, for one reason is coordination – that will persuade that
> the X or Y format is the way to go (I personaly treat availability of
> Stata 11 manuals in PDF as a hint what that format might be), for the
> second reason that technical solutions could be suggested by the
> developers (e.g. they may or may not accept the changes to the -help-
> behavior, thus eliminating the need in -phelp-, etc). Finally, as the
> do-files editor currently has syntax highlighting, it could be useful
> to expand it to highlight syntax in SMCL files, and provide it with
> some “write your command name here” templates.
>
> Sergiy Radyakin has compiled into this summary and added his comments
> to the ideas and opinions expressed in the statalist discussion “TeX
> template for PDF help files” by the following contributors: Kit Baum,
> Nick Cox, Roy Wada, Phil Schumm, Richard Williams, Mark Schaffer,
> Martin Weiss, David Airey and others who devoted their Sunday time to
> this discussion.
>
> Thank you very much!
*
* For searches and help try:
* http://www.stata.com/help.cgi?search
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
