embedding one kind of syntax inside another: is it kludge or clever?

Question

Background: Recently while looking at a "structured text editor" I noticed they used a trick to change python/perl/c++/java et al. into a "structured" outline by sneaking XML into the comments of the respective languages.

I remembered seeing this trick inside a windows bat file once as well. The REM statements of the bat file were used to "hide" some perl code.

Question: Have you ever seen an instance where someone used the comments of a programming or markup language to embed the syntax of an entirely different language? If yes, can you give a link to the example or explain what it was?

If you have not, here is an example:

• An example of an editor file format that uses this trick.

Question: Is this kind of "trick" a clever and useful idea? If so, can you enumerate a special instance where you used this trick? If no, can you describe why you think it is a bad idea?

Answer 1

I can't give you a full answer, but Netbean likes to use this trick with their Java generated code.

The problem is, Java source code should be a medium between applications. By adding meaning to certain comments, you are forced to stick with Netbeans only. Sure the comments can just be ignored by other programs, but what if these comments get moved or changed? I've done that in Netbeans and then some funkiness occurred when I tried loading the file back in Netbeans. I had to take time to fix the syntax (in comments!) that was suppose to be invisible to me.

Personally, I would never add more meaning to an existing file if it required more than one non-local modification (meaning, its ok to have meaning within one comment, but don't have a meaning from this comment to that comment). I would definitely add another file that contained the required metadata in most cases.

Answer 2

You're speaking of polyglots, an absolutely fascinating aspect of computer programming and a wonderful exercise in the ambiguous nature of some scripting/programming languages. While most definitely an intriguing notion, they are rarely seen outside of the arena of novelty. Speaking from the standpoint of a coder, however, it would most definitely be a feat to get your work to function in several, vastly different environments; seeing, however, as polyglots generally rely on all sorts of hacks and work-arounds via comments, this is almost always outside of the realm of feasibility. Definitely worth a look if you haven't seen what they can do, though; I'll recommend this one.

Believe it or not, that single file will properly compile (in some way, shape, or form) in fifteen separate languages:

1. HTML
2. bash
3. zsh
4. C89
5. C99
6. C++
7. Makefile
8. Ruby
9. Tcl
10. Perl
11. Haskell
12. Python
13. JavaScript
14. Brainfuck
15. Whitespace

Answer 3

This horror interposes valid XHTML, HTML and pre-HTML3.2 tagsoup 'hiding' markup with CSS comments:

<style type="text/css"><!--/*--><![CDATA[/*><!--*/
    ...
/*]]>*/--></style>

I was mortified when I started seeing it actually used. It was only meant as an exercise. Sorry.

Answer 4

I've seen this trick (hiding stuff in the comments) used to folding in editors, for documentation markup in various tools, and for leaving breadcrumbs for round-trip work in a modeling tool.

The other use I've seen is in Cog, a code generator. You write python inside comments and then Cog runs the python to generate code. It's interesting because the entire point is to never need/want to modify the generated code, so it doesn't run into the same set of annoyances you get with, for instance, a folding editor when you accidentally mess up the 'fold' comments in a different editor.

Answer 5

Visual studio has a form of this called T4. Unfortunately, the documentation is kind of sketchy.

Answer 6

One favourite markup used in documentation for Python is Restructured Text. Its a general simplified markup language, like Markdown or Textile, but it makes for good documentation structure and can easily be used to generate HTML or PDF documentation.

Answer 7

Donald Knuth's WEB and CWEB embed Pascal (WEB) and C (CWEB) inside TeX. Here is an example from the METAFONT source code:

@ The following system-independent code makes the |xord| array contain a
suitable inverse to the information in |xchr|. Note that if |xchr[i]=xchr[j]|
where |i<j<@'177|, the value of |xord[xchr[i]]| will turn out to be
|j| or more; hence, standard ASCII code numbers will be used instead of
codes below @'40 in case there is a coincidence.

@<Set init...@>=
for i:=first_text_char to last_text_char do xord[chr(i)]:=@'177;
for i:=@'200 to @'377 do xord[xchr[i]]:=i;
for i:=0 to @'176 do xord[xchr[i]]:=i;