Non-text format for source code

Then you get into which HTML subset you allow that does not have deprecated or browser specific HTML tags

Why not to take just what's needed from, say, [1]?

There's a catch, however: to make the better use of XML processing tools and libraries, there should be a way to write the code itself in XML, too. Of which the only example I know is XSLT, and I'm not certain if it's a particularly good one.

The trouble is every tool will have its own different implementation which wont necessarily be compatible. Even XHTML across browsers is bad enough, let alone effectively vendor specific extensions.

And great another three layers of DLL and bloatware potentially, which of course will be different on each platform and platform version :-)

:D As if the bloatware is insufficient at its present what, 99+%? of all ware indeed...

But including a few html links and images in the source comments could be practical. If they point to resources in the same archive, at least. Even if the source would confuse browsers etc. copying the link is not a big deal anyway. If someone finds *that* a big deal then programming should not be that persons job of choice. Which I suppose is the reason why we stick with plain ASCII to this day; nothing has beaten the Latin alphabet for millenia, in fact it has beaten lots of hieroglyph based languages. So it can't be all bad, I suppose, we should stick to it for the time being.

Dimiter

------------------------------------------------------ Dimiter Popoff Transgalactic Instruments

------------------------------------------------------

I think to really do what Vladimir wanted it would need a full "compound document" format, like ODF perhaps. So he can do what he wants in the document, include pictures, spreadsheets, videos, a facebook game, whatever. Actual code would be formatted in a "code" style, say. A preprocessor (possibly a macro) would extract these into a source code file and call make etc.

Sounds awful :)

Yes it does.

What about the other way around? Compilable code files as the main format, with commands embedded in comments to include graphics, control the page layout, update/retrieve file from SCM, etc.

A dedicated "browser" (for lack of better term) cowould bring all the components needed to display a compound document, while a language compiler will just process the files as-is.

Sounds awful :)

Yes it does...

R.

PS: As others pointed out, I believe literate programming tools already can do that. (Anything that Tex/Latex can do could be available.) The result will be anything but easy to use.

But that is what doxygen et al already do AIUI.

I think that was me. I have a programming textbook or two written using this technique, which is explained a bit in the first chapter. ("C interfaces and implementions" by Hanson). Good book I thought.

Doxygen has this covered.

And I expect that most compilers are quite happy for you to use a slightly wider character set (Latin-1, UTF-8, etc.) in comments, even if you can't use them in actual program identifiers.

Indeed it does sound terrible.

But perhaps Vladimir could tell us what he wants - there seems to be a lot of guessing going on in this thread. There has been some interesting discussion and ideas here, but I don't think we are helping the OP much. (This is no bad thing, of course - after all, these are discussion groups rather than helplines.)

Sounds like you are looking for a "litterate programming" tool.

At least one ISO standardised programming language allows source text to be stored in non-text files, but it doesn't look like any of the compiler writers have felt any compelling reasons to use the permission to embed documentation and source text in the same files.

I have never tried to use litterate programming tools myself, so I'm not sure how sensible/impractical it is. (But I do have a suspicion that it is impractical.)

I am not sure the benefit from embedding documentation and source text in the same file alone is big enough to make the change worth it. If you went a step further and left the sequential-stream-of-characters paradigm in favour of some kind of higher dimensional structure (2D with layers may be as much as most humans can manage), there might be sufficient benefits to make it worth switching source paradigm. Unfortunately I can't quite come up with a sensible way of doing it. And I fear that the standard easily would be much too incomprehensible.

Greetings,

Jacob

There's still a chance -- I wouldn't call it "hope", but I'll call it a "chance". Consider version control. Once upon a time version information was left to comments and ad hoc external documents. Now it's official, organized, and thank goodness for that.

Mel.

We have been using our DocGen tool for over 15 years. We wouldn't do it if it wasn't practical.

The benefit is in the process. To make best use you have to wite the documentation for the procedure at the same time as you write the code. The documentation serves as a specification. We end up with fewer bugs.

As a corollary, we often have to perform this process when we take in code from third parties. The process always reveals bugs.

Stephen

I believe Windows Help files were generated this way. You write your text normally using Winword, and mark commands with a special style, which the help file compiler interprets along with the regular text. I also did something similar a while ago, using StarWriter for DOS :-)

Adapting that to extract all text written in a particular style and place it into a *.c file would not be a problem.

But then you have the usual problems of a rich-text editor trying to generate not only formatted text, but also structure. Is this word in a monospaced font because I have set it to monospaced, or is it because I applied the "code" style? Thanks, I prefer a plain text editor with syntax coloring.

Stefan

Most if not all compilers that support 8 bit chars (as opposed to truncating to 7 bits) will support extended wider character sets.

I think that was an issue in the design of the character extensions and comment delimiters in most languages.

Missing from most of the discussion has been the intended audience. Are we documenting an application design and doing a running implementations with the design as a handy reference. Are we documenting the implementation considerations or are we providing user documentation.

I'm sure that most is part of all of the above, but the considerations and requirements are different for each.

Order is also significant. I personally use spread sheets to gather material for a project. In truest sense of an electronic blackboard with spec pages, images and design calculations spread out on several pages.

User requirements and documentation come next in a document that eventually has implementation choices and implementation overview documented. I personally like to keep the actual code sparse of additional material so I have a better overview of the code when reading through it.

This too is a strawman guessing at Vladimir's intentions.

w..

In some fields of embedded programming, this paradigm switch is taking place right now, usually in the form of higher-level representations that are compiled into C source code as an intermediate step: state machines, UML diagrams, MatLab-to-C conversion, AUTOSAR generators, etc.

In some sense one can think of these approaches as literate programming on steroids.

Model driven engineering, it is gaining ground in the industry, and out of the universities.

"We cannot fix this problem in our model because the generator does not support that. Please work around it in the adaption layer and fake the inputs to the model accordingly."

"I'm not making a function 'send(int messageCode)' and an enum for message codes, because my modeling tool doesn't let me model free functions. Instead, I'm making a class for each message (complete with clone(), serialize(), etc. methods). Yes, that's 20x as much code, but at least it can be modeled."

Brave new world.

Stefan

I understand you have had problems but not all tools are alike, and besides, I said it was gaining ground not that it was established. There are already modellers for avionics and the constraints are severe.

What we need though are base level standards; international ones that vendors will embrace (which I think means they have to seriously and profoundly participate in the process, including folks supporting gnu.)

I don't need ad-hoc stuff for clients. I need a base level standard they can depend on as a foundation. Proprietary additions are fine, so long as there is enough to work with in the base level that I don't have to use them.

Jon

:D :D ROFL, don't we have that for decades now (just substitute "compiler" for "modeling tool").

Evolution will have its way though, one way or the other. Glitches like going to a too high level (as is the case with programming languages now, nobody has written even decent prose during the millenia relying on phrase-book knowledge of the respective language) or losing basic skills and relying on stupid (or may be not that stupid) automatons to do things people are just lazy to be bothered with are inevitable. Some of them of them may and will last a lot longer than a persons lifetime - a negligible period of time when it comes to evolution and the correction it will make, though.

Dimiter

------------------------------------------------------ Dimiter Popoff Transgalactic Instruments

------------------------------------------------------