Non-text format for source code

[Vladimir Vassilevsky]

For great many reasons, it would be convenient to have source code in some
rich format rather then plain ASC text. I could think of embedding
illustrations, links and data into file, custom coloring, individual styles,
comments, automatic macro expansion, presets and other features offered by
modern word processors. The idea seems obvious; so there should be a tool
for that already. That could be a pre-processor to import/export source text
to/from some popular format such as *.doc or *.xml.
Do you know of such tool ? Any comments?

Vladimir Vassilevsky
DSP and Mixed Signal Consultant
www.abvolt.com

[John Devereux]

"Vladimir Vassilevsky" <nos...@nowhere.com> writes:

> For great many reasons, it would be convenient to have source code in some
> rich format rather then plain ASC text. I could think of embedding
> illustrations, links and data into file, custom coloring, individual styles,
> comments, automatic macro expansion, presets and other features offered by
> modern word processors. The idea seems obvious; so there should be a tool
> for that already. That could be a pre-processor to import/export source text
> to/from some popular format such as *.doc or *.xml.
> Do you know of such tool ? Any comments?

Presumably you are familiar with doxygen et al?


--

John Devereux

[Dave Nadler]

We use Doxygen for some projects - works well.
Its just for documentation though, no source pre-processing,
no viewing of your source as through a nice word processor.
Hope that helps,
Best Regards, Dave

[John Devereux]

OK, I have not used it seriously. I am surprised there is no way to
include the source code in the output?

There is the "literate programming" idea:

<http://en.wikipedia.org/wiki/Literate_programming>



--

John Devereux

[Walter Banks]

Vladimir Vassilevsky wrote:

> For great many reasons, it would be convenient to have source code in some
> rich format rather then plain ASC text. I could think of embedding
> illustrations, links and data into file, custom coloring, individual styles,
> comments, automatic macro expansion, presets and other features offered by
> modern word processors. The idea seems obvious; so there should be a tool
> for that already. That could be a pre-processor to import/export source text
> to/from some popular format such as *.doc or *.xml.
> Do you know of such tool ? Any comments?

There already are some examples of this.

Up to now non ascii representations for text based languages have a
simple way that ascii is fed to most compilers. Comments and design
notes are one thing but ways of having several related pieces of
information become possible like unit tests as part of the source
and uls to test files on the internet

This changes a lot when non text is part of meaningful syntax for a language.
There are a couple examples of this ISO/IEC 61131 is a standard
describing programming for ladder logic and block programming .
ISO/IEC 61499 is an extension to block programming in 61131.

I wrote a parser for 61131 and it actually isn't that bad. Essentially
the first step is extracting the date relationships between blocks
into a data base and then compiling the data base

w..

[dp]

HTML sources, eh? Why not, come to think of it...

Dimiter

[Nick Leverton]

In article <87sj5h8...@devereux.me.uk>,

John Devereux <jo...@devereux.me.uk> wrote:
>Dave Nadler <d...@nadler.com> writes:
>
>> We use Doxygen for some projects - works well.
>> Its just for documentation though, no source pre-processing,
>> no viewing of your source as through a nice word processor.
>> Hope that helps,
>
>OK, I have not used it seriously. I am surprised there is no way to
>include the source code in the output?

Doxygen, not suprisingly, has options for this.

I shall forbear to mention POD in embedded company ...

Nick
--
"The Internet, a sort of ersatz counterfeit of real life"
-- Janet Street-Porter, BBC2, 19th March 1996

[Dave Nadler]

On Thursday, January 31, 2013 3:15:38 PM UTC-5, John Devereux wrote:

> Dave Nadler writes:
> > We use Doxygen for some projects - works well.
> > Its just for documentation though, no source pre-processing,
> > no viewing of your source as through a nice word processor.
> > Hope that helps,
>
> OK, I have not used it seriously. I am surprised there is no way to
> include the source code in the output?

There may well be; certainly declarations can be output.
But this isn't like working with source code in a WSIWYG
editor including diagrams, highlighting, font control...
Which is what I understood Vladimir was asking about ?
It would be great to have these features as long as it
worked in conjunction with other IDE-like behavior (ie
macro expansion, accumulation of diagnostic info, etc).

An Eclipse plug-in anyone ?

Right now I'd just settle for a stable IDE that didn't
get confused and require me to delete mysterious intermediates
that it doesn't "clean"...

Interesting !
Best Regards, Dave

[David Brown]

On 31/01/13 23:09, Dave Nadler wrote:
> On Thursday, January 31, 2013 3:15:38 PM UTC-5, John Devereux wrote:
>> Dave Nadler writes:
>>> We use Doxygen for some projects - works well.
>>> Its just for documentation though, no source pre-processing,
>>> no viewing of your source as through a nice word processor.
>>> Hope that helps,
>>
>> OK, I have not used it seriously. I am surprised there is no way to
>> include the source code in the output?
>
> There may well be; certainly declarations can be output.

Doxygen can quite happily include the entire source code in the output
if you want - both in a function-for-function arrangement along with the
documentation, and in complete files. It all has syntax highlighting,
clickable cross-references, searchable indexes, etc.

But it is an output generated from the source code - it is not editable.

I can't think /why/ one would want to edit these "rich format" parts
within the source code, however. If you were able to change the font
colour, weight or style within the source code, then you would lose all
advantages of syntax highlighting.

If you've got documentation, diagrams, pictures, etc., that are part of
your "source code", then keep them together with the source code. But
there is no need to force them to be within the same files, or use the
same editor. I've done projects where pictures were part of the
"source" - they are stored as bmp files, and the Makefile-controlled
build runs a converter to generate a "const uint8_t picture[] = ..."
array from the file whenever it changes. There is /nothing/ to gain
from trying to include that picture within another C source file. I
also have diagrams in projects - if they are simple, they might be
included in the source code comments, but mostly they are in a separate
.dot file so that they don't distract from the source code. Doxygen
puts it all together in the end.

> But this isn't like working with source code in a WSIWYG
> editor including diagrams, highlighting, font control...
> Which is what I understood Vladimir was asking about ?
> It would be great to have these features as long as it
> worked in conjunction with other IDE-like behavior (ie
> macro expansion, accumulation of diagnostic info, etc).
>
> An Eclipse plug-in anyone ?
>
> Right now I'd just settle for a stable IDE that didn't
> get confused and require me to delete mysterious intermediates
> that it doesn't "clean"...

It would be nice if Eclipse's build system worked better. Personally, I
prefer my own Makefiles - they are much better than Eclipse at
rebuilding /exactly/ what is needed, no more and no less. Eclipse is
particularly bad at re-generating dependency files unnecessarily - for
large projects, this can be time consuming.

[Jon Kirwan]

For me, the issue is that I'd like to have a document that I
directly edit and work with (not unlike using DreamWeaver,
for example, in editing HTML) that supports the inclusion of
good diagrams and perhaps, if I'm crazy enough, a short video
tutorial if I'm in the mood to produce it.

I suppose a simple example (but not a definitive one) would
be the insertion sort code. It's very simple to write, but a
newcomer might be able to "see" it still better if I included
a diagram showing the left part as "sorted", a right part as
"unsorted", and the latest element picked off of the left
side of the right part which is being inserted into the left
part. Yes, this is a silly example. Anyone worth their salt
already knows several sorts and most certainly this one. But
that's beside the point. The point is that there exist cases
where I _DO_ want to include some special help because the
way the function operates is enough interesting that it
deserves some extra effort in documenting it. Not just for
others, but for me too when and if I return to it some other
day.

I take some of the points made by the literate programming
advocates, too. (There are some terrible examples held out as
good examples, yes. But there are good examples held out as
good examples, which really are good examples, too.) There
are times when the best way to talk about the code design
doesn't exactly follow the best way to lay out the code for a
compiler. It would also be nice to have the ability to
arrange what I say about things, together with the code that
does these things, to be different than the way a compiler
must see them and to have that handled so that all I (or
anyone else) sees is the source as I intended the source to
appear for purposes of best communication, not for compiler
consumption. That would be ANOTHER desire of mine, as well.
At least, sometimes and in some places.

It seems to me that in this day of so much work on standards,
which include not only HTML5 but also XML and many others,
that we could have compilers which aren't stuck parsing
simple ASCII text. It was fantastic (and the only way to go)
when all I had was an ASR-35 clacking away and a video
display (if you dared to even consider the idea) could set
you back US$40,000 or more. (I wonder how many remember the
old Plato terminals?) But today? With workstations absolutely
everywhere? And disk space almost as cheap as dirt (though
not nearly as likely to serve its purpose quite as long?) Not
just one video display; nay, not even two; but often three
per workstation??

><snip>

Jon

[Grant Edwards]

On 2013-02-01, David Brown <da...@westcontrol.removethisbit.com> wrote:

> Doxygen can quite happily include the entire source code in the
> output if you want - both in a function-for-function arrangement
> along with the documentation, and in complete files. It all has
> syntax highlighting, clickable cross-references, searchable indexes,
> etc.

The main problem with the output from Doxygen is that it's wrong.

The comments are wrong, therefore any output based on the comments is
wrong.

OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
time, the Doxygen-generated docs for embedded stuff that I've come
across was worse than useless.

There are just too many cases where the function description,
parameter list, and return values are just plain wrong. Somebody
always ends up refactoring the code, changing the calling conventions,
and so on without updating the comments.

Right now I'm using an industrial protocol stack library from a third
party vendor. It comes with tens of meagabytes of Doxygen generated
stuff. The first time I looked up a function in the Doxygen docs, the
parameter list didn't even match the code. The next time, the
parameter _names_ were correct, but the description of one of them was
completely wrong. I deleted the docs at that point.

--
Grant Edwards grant.b.edwards Yow! I just heard the
at SEVENTIES were over!! And
gmail.com I was just getting in touch
with my LEISURE SUIT!!

[Stephen Pelc]

On Fri, 1 Feb 2013 15:30:40 +0000 (UTC), Grant Edwards
<inv...@invalid.invalid> wrote:

>The main problem with the output from Doxygen is that it's wrong.
>
>The comments are wrong, therefore any output based on the comments is
>wrong.
>
>OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
>time, the Doxygen-generated docs for embedded stuff that I've come
>across was worse than useless.

This has all got very little to do with Doxygen. It's much more
a process problem. What has happened is that generating the
documentation is not part of the release or build process. Once
you realise that building the documentation should happen as part
of a issue build process, these faults go away.

We (MPE) have been using our own proprietary literate programmming
system for the last 15 years or so. We are regularly told that our
documentation is good. However, I have had to wave a big stick many
times to ensure that house rules are obeyed.

The big issue with all forms of literate programming is to keep
function documentation alongside the function itself in the source
code. One of the downsides of Doxygen is the visual separation of
function declarations and parameter documentation.

Stephen

--
Stephen Pelc, steph...@mpeforth.com
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web: http://www.mpeforth.com - free VFX Forth downloads

[Grant Edwards]

On 2013-02-01, Stephen Pelc <steph...@mpeforth.com> wrote:
> On Fri, 1 Feb 2013 15:30:40 +0000 (UTC), Grant Edwards
><inv...@invalid.invalid> wrote:
>
>>The main problem with the output from Doxygen is that it's wrong.
>>
>>The comments are wrong, therefore any output based on the comments is
>>wrong.
>>
>>OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
>>time, the Doxygen-generated docs for embedded stuff that I've come
>>across was worse than useless.
>
> This has all got very little to do with Doxygen.

Of course. It's the age-old problem of the comments being wrong.

> It's much more a process problem. What has happened is that
> generating the documentation is not part of the release or build
> process.

No, that wasn't the problem in this case. The problem was that the
information in the comments in the source code which was being
extracted were wrong. The documentation matched the comments in the
code. The comments didn't match the code.

> Once you realise that building the documentation should happen as
> part of a issue build process, these faults go away.

Unfortunately, they don't. Anything that is being produced from
comments is wrong often enought that it can't be trusted and you
always have to look at the actual source code.

The function name/type and parameter name/type should always be right,
since that can be parsed from the actual source code. But, some
documentation systems I've seen don't do that. They rely on comments
for that as well.

> The big issue with all forms of literate programming is to keep
> function documentation alongside the function itself in the source
> code.

In my experience, that doesn't seem to help much. Comments that are
located _on_the_same_line_ as C code are wrong often enough that I
generally ignore them.

> One of the downsides of Doxygen is the visual separation of function
> declarations and parameter documentation.

The downside of any sort of documentation system is that it seems be
viewed by many as an alternative to writing code that's easy to read
and understand.

--
Grant Edwards grant.b.edwards Yow! ... this must be what
at it's like to be a COLLEGE
gmail.com GRADUATE!!

[Mel Wilson]

Stephen Pelc wrote:
> This has all got very little to do with Doxygen. It's much more
> a process problem. What has happened is that generating the
> documentation is not part of the release or build process. Once
> you realise that building the documentation should happen as part
> of a issue build process, these faults go away.

People seem to think it is. They turn out that documentation and they offer
it to the public. The ones I run into tend to be huge pages containing
nothing but nouns. Seriously, the one I read in depth had a page footer,
and it contained the word 'for', which is a preposition, and a version
number which could be called an adjective. Apart from those -- nouns. It
would have been nice to find some verbs to tell me about what would actually
get done.

Mel.

[Dave Nadler]

On Friday, February 1, 2013 10:30:40 AM UTC-5, Grant Edwards wrote:
> The main problem with the output from Doxygen is that it's wrong.
> The comments are wrong, therefore any output based on the comments is
> wrong.
>
> OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
> time, the Doxygen-generated docs for embedded stuff that I've come
> across was worse than useless.

I've certainly seen that too. Documentation has to be maintained
(updated, reviewed) as a serious part of development rather than
an afterthought. If it isn't part of the regular build process
the generated stuff will degrade to useless. If its done well and
*regularly used by developers who need it* this can be really
helpful ! If its done to check a box and/or nobody uses it,
useless...

[Ivan Shmakov]

>>>>> Jon Kirwan <jo...@infinitefactors.org> writes:

[...]

> For me, the issue is that I'd like to have a document that I directly
> edit and work with (not unlike using DreamWeaver, for example, in
> editing HTML) that supports the inclusion of good diagrams and
> perhaps, if I'm crazy enough, a short video tutorial if I'm in the
> mood to produce it.

Well, I'm getting the same feeling occasionally; e. g., when
posting to a Usenet newsgroup [aside: cross-posting to
news:news.misc]. Still, even as there are standard ways of
including all the sorts of nice stuff (such as SVG diagrams, or
digital signatures) into Usenet messages, there're those who'd
oppose even the inclusion of non-ASCII characters (or, if a
non-English newsgroup is considered, the use of an encoding
other than a prescribed one) or OpenPGP signatures along with
the message, even if done according to the standards.

Somehow, I come to believe that the use of a message format more
elaborate than "pure ASCII" (say: HTML5/XML) for email-like or
news-like communication may have its benefits. (Perhaps as well
as the use of such a format for the source code.)
Unfortunately, there's a catch...

[...]

> It seems to me that in this day of so much work on standards, which
> include not only HTML5 but also XML and many others, that we could
> have compilers which aren't stuck parsing simple ASCII text. It was
> fantastic (and the only way to go) when all I had was an ASR-35
> clacking away and a video display (if you dared to even consider the
> idea) could set you back US$40,000 or more. (I wonder how many
> remember the old Plato terminals?) But today? With workstations
> absolutely everywhere? And disk space almost as cheap as dirt
> (though not nearly as likely to serve its purpose quite as long?)
> Not just one video display; nay, not even two; but often three per
> workstation??

... The problem is that these new facilities, once they appear,
are most surely going to be misused.

For an example, take a look at the contemporary Web [aside:
cross-posting to news:comp.infosystems.www.misc, too]. Every
other Web page is designed as if it's some kind of picture, not
a text (which it is, first and foremost.) Digging a bit into
CSS, what you're likely to find? Here comes an example:

body {
width: 1024px; /* 'cause everybody's screen is at least that wide */
font-size: 14px; /* it's enough for everyone, no? */
}
#leftbar { width: 384px; /* that's about 40 characters; good */ }
#forum { width: 768px; /* that's the rest of the screen */ }

Naturally, as soon as the reader of the Web page opts for
another font size (e. g., my preference would be no less than
20px), the design is screwed up instantly. (Not that this issue
is not relevant to the source code as it is right now: we have
those who adhere to the 80 characters per line limit, and those
-- who use newer code editors and IDE's, and wider screens or
smaller fonts, -- who don't; we have those who indent with 2
spaces per nesting level, and those who use 8; etc. And while a
switch to a non-ASCII code representation may obviate some of
these issues, it will certainly bring a bunch more.)

Given all the sorts of such poor designs I've seen on the Web,
I'd hesitate to use a system which /requires/ the code to be
worked on in a "WYSIWYG" fashion. Why, for the Web, my browser
of choice is Lynx, specifically for its ability to ignore CSS,
images, and all of such "creative freedom" that's so easy to
misuse. I still believe that there /are/ valid uses of such
technologies, both existing and to be developed, but for me,
there remains a big fat warning regarding their possible (as in:
most certain) misuse.

Hopefully, the technologies of tomorrow will come with some kind
of "safety mechanisms" against such...

PS. Also to note is that I don't know of any version control system
with good support for non-line-oriented data. Somehow, I feel
that even computing the "difference" (as in: diff(1)) between
two trees (as in: XML) is much more an issue than computing one
between two lists (as in: ASCII text.)

--
FSF associate member #7257

[Dave Nadler]

On Friday, February 1, 2013 12:05:52 PM UTC-5, Grant Edwards wrote:
> The downside of any sort of documentation system is that it seems be
> viewed by many as an alternative to writing code that's easy to read
> and understand.

True, but extrapolate that too far and you get "comments are bad".
Good code makes it really clear what the code DOES.
Good documentation makes it really clear WHY;
what's the purpose and organization (as contrasted to function) ?
The worst comment I've ever seen (more than once !): // Add 1 to i

Good documentation allows quicker understanding of
code structure and a good Doxygen tree is *really*
helpful and can save hours of grep'ing and head-scratching.

But it takes discipline to do it !

[dp]

On Feb 1, 9:06 pm, Ivan Shmakov <oneing...@gmail.com> wrote:
> ...

>         Hopefully, the technologies of tomorrow will come with some kind
>         of "safety mechanisms" against such...

I think we do not need "tomorrow"s technologies to make most
if not all of Vladimir's suggestion.

Me, I would just include html links in the source such that
they will be treated as comments by the compiler/assembler/whatever
and be done with it. Without a lot of effort the source will
be both compilable and viewable with a browser, pictures
and all.
Now, I just put it all in a directory or make the suitable directory
tree so it will still be quite easy for anyone to locate the
relevant information but I can see how Vladimir's idea could
save time for someone seeing something I have done for the
first time. Even to me if I look at it some 10 years later
(though I must say I don't have much if any of a problem
reading 20 and even almost 30 years old sources of mine;
writing the correct comments is the most important part
when it comes to readability, after all).

Dimiter

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

http://www.tgi-sci.com
------------------------------------------------------
http://www.flickr.com/photos/didi_tgi/sets/72157600228621276/

[Dombo]

Op 31-Jan-13 23:09, Dave Nadler schreef:

> On Thursday, January 31, 2013 3:15:38 PM UTC-5, John Devereux wrote:
>> Dave Nadler writes:
>>> We use Doxygen for some projects - works well.
>>> Its just for documentation though, no source pre-processing,
>>> no viewing of your source as through a nice word processor.
>>> Hope that helps,
>>
>> OK, I have not used it seriously. I am surprised there is no way to
>> include the source code in the output?
>
> There may well be; certainly declarations can be output.

Doxygen definitely can include (hyperlinked) source code; I use that all
the time. It can also include diagrams, formulas..etc (never used it,
but there are tags for that).

> But this isn't like working with source code in a WSIWYG
> editor including diagrams, highlighting, font control...
> Which is what I understood Vladimir was asking about ?
> It would be great to have these features as long as it
> worked in conjunction with other IDE-like behavior (ie
> macro expansion, accumulation of diagnostic info, etc).
>
> An Eclipse plug-in anyone ?

Don't forget the diff and a merge tool. It would pretty useless without
those.

[Dombo]

Op 01-Feb-13 16:30, Grant Edwards schreef:

> On 2013-02-01, David Brown <da...@westcontrol.removethisbit.com> wrote:
>
>> Doxygen can quite happily include the entire source code in the
>> output if you want - both in a function-for-function arrangement
>> along with the documentation, and in complete files. It all has
>> syntax highlighting, clickable cross-references, searchable indexes,
>> etc.
>
> The main problem with the output from Doxygen is that it's wrong.
>
> The comments are wrong, therefore any output based on the comments is
> wrong.
>
> OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
> time, the Doxygen-generated docs for embedded stuff that I've come
> across was worse than useless.
> There are just too many cases where the function description,
> parameter list, and return values are just plain wrong. Somebody
> always ends up refactoring the code, changing the calling conventions,
> and so on without updating the comments.

You can hardly blame Doxygen for that. Though I agree that programmer
supplied comments often are misleading either due to refactoring or just
mindless copy-and-pasting (sometimes it would have been better if the
clipboard functionality were never invented).

Though I use Doxygen quite often to get familiar with an code base, I
rarely read the programmer supplied comments. I mostly use Doxygen to
figure out the structure of the code.

> Right now I'm using an industrial protocol stack library from a third
> party vendor. It comes with tens of meagabytes of Doxygen generated
> stuff. The first time I looked up a function in the Doxygen docs, the
> parameter list didn't even match the code. The next time, the
> parameter _names_ were correct, but the description of one of them was
> completely wrong. I deleted the docs at that point.

I have seen the same happen with manually maintained Word documents that
describe the code in too much detail. Unless one is willing to invest
significant effort into writing _and_ maintaining proper documentation
with the needs of the user in mind (as opposed to just following the
requirement "there shall be documentation"), the result is more often
than not worse than useless.

I recently participated in a review meeting about a coding standard to
be used in that organization. They wanted a rule that required every
function to be fully documented. Having been-there-and-done-that and
having seen tons of pointless and misleading comments, my recommendation
was to rewrite that rule to: don't write comments unless they have added
value.

[Paul]

In article <bcSdndILtuFgXpfM...@giganews.com>,
nos...@nowhere.com says...

>
> For great many reasons, it would be convenient to have source code in some
> rich format rather then plain ASC text. I could think of embedding
> illustrations, links and data into file, custom coloring, individual styles,
> comments, automatic macro expansion, presets and other features offered by
> modern word processors. The idea seems obvious; so there should be a tool
> for that already. That could be a pre-processor to import/export source text
> to/from some popular format such as *.doc or *.xml.
> Do you know of such tool ? Any comments?
>

Sorry all these fancy things like 'workspaces' and 'projects' on IDEs
and the like assume that that software or that file is the WHOLE project
and we can be LAZY. Documentation exists in many forms and from many
sources, the process must allow for updating ALL associated
documentation.

I have seen so many problems where people dont know what something
is made to even for ASICs, I come to design the tester system and all
the documentation contradicts itself from original to spec to final
design.

Anything which has funky formatting suffers from

1/ inability to run diff
2/ Which doc or XML or other strange format and version of it
3/ Will the format always be backward compatible even in saving
corrections
4/ Anything with links is great for a product lifespan of SIX months
MAX
a/ links to dataheets get pulled, reshuffled or company goes under
b/ external links are always ephemaral
c/ even links to your own docs are subject to
i) Vagueries of drive mappings on networks
ii) Most packages will insist on ABSOLUTE paths only to
C:\My Documents\....
C:\Programme Files\Stupid IDE\Workspace\...
d/ Use of fonts and colours is VERY system dependant what if that
font is not loaded on that system or worst still no alternative
scheme is given as people will always have Colibri on their system
The colour scheme has been renamed
5/ The IDE that reads this file is no longer supported as the company
who make it have gone bust, been bought out.
6/ No doubt the resulting document can only be read by that software
on that system with that resolution of screen.

I have done a lot of work even with special document archives for
museums and the like, and PDF Archive format will ONLY allow about
FOUR fonts in it (Courier, Times [Mew Roman], Helvettica/Arial and one
other).

Basically the code must always be readable, unless you really expect to
write once and BIN it.

--
Paul Carpenter | pa...@pcserviceselectronics.co.uk
<http://www.pcserviceselectronics.co.uk/> PC Services
<http://www.pcserviceselectronics.co.uk/fonts/> Timing Diagram Font
<http://www.gnuh8.org.uk/> GNU H8 - compiler & Renesas H8/H8S/H8 Tiny
<http://www.badweb.org.uk/> For those web sites you hate

[Paul]

In article <87pq0j4...@violet.siamics.net>, onei...@gmail.com
says...

>
> >>>>> Jon Kirwan <jo...@infinitefactors.org> writes:
>
> [...]
>
> > For me, the issue is that I'd like to have a document that I directly
> > edit and work with (not unlike using DreamWeaver, for example, in
> > editing HTML) that supports the inclusion of good diagrams and
> > perhaps, if I'm crazy enough, a short video tutorial if I'm in the
> > mood to produce it.

Anything these days without a youtube link is useless to todays
youngsters :-)

........

> > It seems to me that in this day of so much work on standards, which
> > include not only HTML5 but also XML and many others, that we could
> > have compilers which aren't stuck parsing simple ASCII text. It was
> > fantastic (and the only way to go) when all I had was an ASR-35
> > clacking away and a video display (if you dared to even consider the
> > idea) could set you back US$40,000 or more. (I wonder how many
> > remember the old Plato terminals?) But today? With workstations
> > absolutely everywhere? And disk space almost as cheap as dirt
> > (though not nearly as likely to serve its purpose quite as long?)
> > Not just one video display; nay, not even two; but often three per
> > workstation??
>
> ... The problem is that these new facilities, once they appear,
> are most surely going to be misused.

They are always misused rarely properly used.

> For an example, take a look at the contemporary Web [aside:
> cross-posting to news:comp.infosystems.www.misc, too]. Every
> other Web page is designed as if it's some kind of picture, not
> a text (which it is, first and foremost.) Digging a bit into
> CSS, what you're likely to find? Here comes an example:
>
> body {
> width: 1024px; /* 'cause everybody's screen is at least that wide */
> font-size: 14px; /* it's enough for everyone, no? */
> }
> #leftbar { width: 384px; /* that's about 40 characters; good */ }
> #forum { width: 768px; /* that's the rest of the screen */ }

My view if marketing types want the thing to look the same as printed
paper they should print it on paper, not on the infinite combinations
of screen sizes and resolutions.

My personal bugbear is NEVER specify anything other than images on web
pages in pixels, that is what point (pt) for height and em, el en used
as widths are for oh hang on they come from printing terms... I wonder
why 300+ year old technology definitions still work and the new ones
dont.

[Jon Kirwan]

On Fri, 1 Feb 2013 11:28:04 -0800 (PST), dp <d...@tgi-sci.com>
wrote:

>On Feb 1, 9:06 pm, Ivan Shmakov <oneing...@gmail.com> wrote:
>> ...
>>         Hopefully, the technologies of tomorrow will come with some kind
>>         of "safety mechanisms" against such...
>
>I think we do not need "tomorrow"s technologies to make most
>if not all of Vladimir's suggestion.
>
>Me, I would just include html links in the source such that
>they will be treated as comments by the compiler/assembler/whatever
>and be done with it. Without a lot of effort the source will
>be both compilable and viewable with a browser, pictures
>and all.
>Now, I just put it all in a directory or make the suitable directory
>tree so it will still be quite easy for anyone to locate the
>relevant information but I can see how Vladimir's idea could
>save time for someone seeing something I have done for the
>first time. Even to me if I look at it some 10 years later
>(though I must say I don't have much if any of a problem
>reading 20 and even almost 30 years old sources of mine;
>writing the correct comments is the most important part
>when it comes to readability, after all).

Yeah, that's what I do, as well. However, I happen to
actually LIKE the idea of not having to force others (or me)
to put their fingers into several applications at the same
time just to understand ONE function. It would be nice to
have an international source code standard that goes past
ASCII, after all these years.

But yeah, I do what everyone else does and it works. I can
just imagine something nicer. Sometimes, change doesn't occur
unless you can imagine your goals.

Jon

[Jon Kirwan]

On Fri, 01 Feb 2013 20:53:32 +0100, Dombo
<do...@disposable.invalid> wrote:

><snip>

>I recently participated in a review meeting about a coding standard to
>be used in that organization. They wanted a rule that required every
>function to be fully documented. Having been-there-and-done-that and
>having seen tons of pointless and misleading comments, my recommendation
>was to rewrite that rule to: don't write comments unless they have added
>value.

I agree here! And it's one of the things I ask myself when
writing comments in code.

But just to stay on my earlier point, it does add value
sometimes to include a diagram inline with the function. In
the past, where it was legible enough and useful enough, I've
used ASCII drawings. But it is painful to do and the question
of what value is added in an ASCII drawing is a slightly
different question than it may be were it possible to use
even the most basic drawing tools. I think having them
available inline would modify at least _some_ of what I add
and whether I add it. And in the end, I think it would
improve, not injure, my own output. I can't speak for others,
of course.

Jon

[Mel Wilson]

Jon Kirwan wrote:

> Yeah, that's what I do, as well. However, I happen to
> actually LIKE the idea of not having to force others (or me)
> to put their fingers into several applications at the same
> time just to understand ONE function. It would be nice to
> have an international source code standard that goes past
> ASCII, after all these years.

If you had a "compiler" that stripped away everything not immediately inside
a <code>...</code> block, and handed the code to gcc, then you could invoke
your compiler from the makefile and all would be well, no?

Mel.

[Jon Kirwan]

That's not the issue, though. It's a different concern.

There are a lot of things <I> can do, and have done. What
counts in part, though, are my customers and what the
programmer skillsets and tools they will have access to ten
years from now. I'd be looking for an internationally
_supported_ standard here. Not ad-hoc stuff I cobble
together.

I believe that my clients would benefit from a supported
standard. I don't believe that they would benefit nearly as
much from one-off tools I write. I've done a LOT of that many
years ago. Problem is, I'm not in the business of supporting
those things and I may not be accessible, either. And it adds
to the support load, as well, if they have to adapt them to
new operating system environments.

Anyway, nice try.

Jon

[Stephen Pelc]

On Fri, 1 Feb 2013 17:05:52 +0000 (UTC), Grant Edwards
<inv...@invalid.invalid> wrote:

>Of course. It's the age-old problem of the comments being wrong.
>
>> It's much more a process problem. What has happened is that
>> generating the documentation is not part of the release or build
>> process.
>
>No, that wasn't the problem in this case. The problem was that the
>information in the comments in the source code which was being
>extracted were wrong. The documentation matched the comments in the
>code. The comments didn't match the code.

That's a process problem. If the team doesn't believe that comments
and documentation matter, then you're doomed from the start. This is
culture. The idea that then arises that there shouldn't be any
comments or documentation because it'll probably be wrong.

>> Once you realise that building the documentation should happen as
>> part of a issue build process, these faults go away.
>
>Unfortunately, they don't. Anything that is being produced from
>comments is wrong often enought that it can't be trusted and you
>always have to look at the actual source code.

See above.

>The function name/type and parameter name/type should always be right,
>since that can be parsed from the actual source code. But, some
>documentation systems I've seen don't do that. They rely on comments
>for that as well.

Yes, that is a real problem with Doxygen, but the root cause is
deep in C culture.

>> The big issue with all forms of literate programming is to keep
>> function documentation alongside the function itself in the source
>> code.
>
>In my experience, that doesn't seem to help much. Comments that are
>located _on_the_same_line_ as C code are wrong often enough that I
>generally ignore them.

See above

>> One of the downsides of Doxygen is the visual separation of function
>> declarations and parameter documentation.
>
>The downside of any sort of documentation system is that it seems be
>viewed by many as an alternative to writing code that's easy to read
>and understand.

IMHO the problem is more subtle. Code documentation is for the
maintenance programmer, who is perceived by many as being dull.
The original author is, of course, a genius who doesn't need
comments. Those of us who find themselves maintaining code that
they wrote 20+ years ago know that that the maintainer's job is
just as hard as the author's. Those of us who can still read also
know that the lifetime cost of software is probably three times
the authoring cost also realise that indulging the maintenance
programmers is a "good thing".

[Niklas Holsti]

On 13-02-01 21:22 , Dave Nadler wrote:
> On Friday, February 1, 2013 12:05:52 PM UTC-5, Grant Edwards wrote:
>> The downside of any sort of documentation system is that it seems be
>> viewed by many as an alternative to writing code that's easy to read
>> and understand.
>
> True, but extrapolate that too far and you get "comments are bad".
> Good code makes it really clear what the code DOES.
> Good documentation makes it really clear WHY;
> what's the purpose and organization (as contrasted to function) ?
> The worst comment I've ever seen (more than once !): // Add 1 to i

The very word "comment" is deprecating and invites scattered,
unorganized "commentary" rather than proper reasoned, organized
rationale and description. It was a very unortunate choice of the
programming pioneers, considering the role that "comments" should fill
today.

If we are asked, of course we "know" that the "comments" in source-code
should not be just comments, but should be something more. But I suspect
that there is a bit of subconscious sub-estimation of their worth,
because they are called comments.

To get back to the point of this thread, it seems to me that the idea of
links from source code to documentation is a good one. In addition to
the problems with diff and version control that others have mentioned,
in-line documentation causes problems in high-integrity development,
when any change to the source-code files triggers expensive retesting
and other quality-assurance procedures. In principle, one can try to
argue that changes to "comments" cannot change the executable code, but
even if one proves that by comparing the old and new binaries, the
source-line-to-code-address mapping will be screwed up, as will file
time-stamps and versions. (Well, maybe the "non-ASCII" content would not
count in the source-line numbering.)

For source-code with links to "non-ASCII" documents, someone skilled
with Emacs Lisp (not I, therefore) could probably whip up at least the
viewing/browsing functionality quickly, so that one could click a link
in an Emacs source-code buffer, and bring up the linked document in a
browser window on the side. Or even a word-processor, math program, or
what have you.

I think a side-by-side view of source-code and documents is preferable
to an in-line interleaving. In an in-line view, with the source-code and
"non-ASCII" documentation sharing the same window, it could often happen
that only a small part of the code of a function would be visible at
once, which would make it difficult to understand the overall structure
of the function. It seems to me that this problem is generic to
"literate programming" schemes -- the prose part dilutes the formal
code. Perhaps the problem could be reduced by an editor that could
fold/unfold the non-ASCII stuff... but side-by-side feels better.

I would keep the linked documents in the source-code folders, close to
the source files that link to the documents, so that the links can be
short relative links. This should avoid the problem of links decaying
with time.

--
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
. @ .

[Rich Webb]

On Fri, 01 Feb 2013 22:50:22 GMT, steph...@mpeforth.com (Stephen
Pelc) wrote:

>IMHO the problem is more subtle. Code documentation is for the
>maintenance programmer, who is perceived by many as being dull.
>The original author is, of course, a genius who doesn't need
>comments. Those of us who find themselves maintaining code that
>they wrote 20+ years ago know that that the maintainer's job is
>just as hard as the author's. Those of us who can still read also
>know that the lifetime cost of software is probably three times
>the authoring cost also realise that indulging the maintenance
>programmers is a "good thing".

Twenty years? I tip my hat to you, sir. I find myself looking at
things I did *two* years ago and wondering just what the hell I was
thinking. ("Who was the bloody fool... or, right.") When you're
immersed in the problem and "in the zone," it all seems so obvious.

[Jon Kirwan]

Agreed. And nicely said.

I guess the point we all agree on is that it's not just for
others but for ourselves, too.

Jon

[Richard Damon]

That sounds very much like my thought on the proposal. You define a
"mark up" language that has a compiler that converts your documentation
file into the source code for the target language (like C), and then
have a rule for your makefile that runs that compiler as needed to
extract the source code from the original file.

[Stefan Reuther]

Grant Edwards wrote:
> On 2013-02-01, David Brown <da...@westcontrol.removethisbit.com> wrote:
>>Doxygen can quite happily include the entire source code in the
>>output if you want - both in a function-for-function arrangement
>>along with the documentation, and in complete files. It all has
>>syntax highlighting, clickable cross-references, searchable indexes,
>>etc.
>
> The main problem with the output from Doxygen is that it's wrong.
>
> The comments are wrong, therefore any output based on the comments is
> wrong.
>
> OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
> time, the Doxygen-generated docs for embedded stuff that I've come
> across was worse than useless.

But that's not the fault of Doxygen. That's general developer
sloppiness, and I don't think there's a cure for it.

I have worked with Literate Haskell source code. Remember, Literate
Haskell is specifically designed to make writing documentation along
with the code easy. The average source file contained a few section
delimiters ("Type Definitions", "Private Functions"), and that's it.
Therefore, it isn't any better than the average free or commercial
software project that contains almost no comments other than the license
header and the occasional diatribe how much <insert other software here>
sucks.


Stefan

[Stefan Reuther]

Haskell has a convention ("Literate Haskell") where the code is
delimited by \begin{code} / \end{code}, allowing the source code to be a
LaTeX document. There's no reason this convention would be limited to
Haskell only.


Stefan

[Grant Edwards]

On 2013-02-01, Dombo <do...@disposable.invalid> wrote:

> I recently participated in a review meeting about a coding standard to
> be used in that organization. They wanted a rule that required every
> function to be fully documented. Having been-there-and-done-that and
> having seen tons of pointless and misleading comments, my recommendation
> was to rewrite that rule to: don't write comments unless they have added
> value.

And every time you find yourself about to write a comment stop and ask
yourself

Why is the code so unclear that it needs a comment?

Can I re-write this code so that its obvious what's going on without
a comment?

--
Grant

[George Neuner]

On Fri, 1 Feb 2013 11:22:54 -0800 (PST), Dave Nadler <d...@nadler.com>
wrote:

>On Friday, February 1, 2013 12:05:52 PM UTC-5, Grant Edwards wrote:
>> The downside of any sort of documentation system is that it seems be
>> viewed by many as an alternative to writing code that's easy to read
>> and understand.
>
>True, but extrapolate that too far and you get "comments are bad".
>Good code makes it really clear what the code DOES.
>Good documentation makes it really clear WHY;
>what's the purpose and organization (as contrasted to function) ?
>The worst comment I've ever seen (more than once !): // Add 1 to i

Almost certainly the most useless comment ever seen 8-)

My personal favorite: the original Unix sendmail was approximately
11,000 lines of C. The source contained exactly one comment
pertaining to an initialized global. The comment read: "don't change
this!"

>Good documentation allows quicker understanding of
>code structure and a good Doxygen tree is *really*
>helpful and can save hours of grep'ing and head-scratching.
>
>But it takes discipline to do it !

And to keep out of these discussions. Obviously I lack that
discipline 8-)

[David Brown]

The concept is not limited to Haskell (though the details of
implementation are different for different languages and tools):

<http://en.wikipedia.org/wiki/Literate_programming>


However, systems like this are nothing more nor less than you can do
with perfectly ordinary ASCII-based programming languages along with
tools like doxygen (or javadoc, python docstrings, etc.). The only
difference is that here you are in "documentation mode" by default and
start "code mode" with some sort of delimiter - while with doxygen you
are in "code mode" by default and start "documentation mode" by a
specially formatted comment.

[Jon Kirwan]

Good questions, of course.

But some functions DO require additional specialty
information to show the mental pathway of getting from a
well-trod mental space to some arcane dead-end. An example
that springs immediately to mind from an old project is the
idea estimating the tau of a radioactive decay curve by
taking the log of the ADC data to linearize it, then applying
a standard least square error fitting routine. Some of the
summations drop out because the x(i) values go from 0 to 1 to
2 to... etc., and the ADC data has it's own constant factor
associated with it. The number of data points also varied,
though.

The resulting computation was performed in assembly code on
an ADSP-2105 and ADSP-2111 processor using one ALU op and up
to two data fetch ops per instruction. But the main point
here is that the least square fitting algorithm had some
specialty constants and a very specialized equation that no
one would normally find anywhere else in the literature.
Getting from the usual literature on the subject to the end
point takes a fair amount of work. Since that work was
already done, it helps to document it clearly. It's neither a
LOT of documentation, though, nor is it trivial. It's in a
perfect mid-sized placed where it's just the right bite size
for inline documentation at the head of the module so that
the source of the specific constant values used and the
specific summations chosen are clearly derived and available.

I won't belabor the issue further, though. We can disagree
about what should, or should not, be present in code. Suffice
it that it is MY opinion that in this particular case and for
the client I had, it would have been very appropriate to
include. However, it would be vastly more complex to write in
ASCII and confusing besides. There is no question of that in
my mind, because I actually first attempted to do exactly
that and then gave it up as excessive and obtuse and ugly. So
I retreated to the usual method -- a separate document that
had to be added to source control and monitored and then also
added to the scoping documentation so that newcomers would be
aware of it, as well.

Jon

[dp]

Oh you can ask yourself that once and learn to live with the
obvious "no" answer for the rest of your life allright.

Then get used to commenting your code well. In fact, how to comment
code is something one has to learn the first year if not the first
month when one begins to learn programming.
Misleading people that comments can be unnecessary is one of the
most counterproductive achievements of the high level languages
last 2+ decades, its debilitating impact is to be carried with
the industry for years if not decades - and who knows how much
longer it will even stay as unnoticed as it is now.

Uncommented code is just garbage.

[Jon Kirwan]

On Sun, 3 Feb 2013 12:31:25 -0800 (PST), dp <d...@tgi-sci.com>
wrote:

>On Feb 3, 8:25�pm, Grant Edwards <inva...@invalid.invalid> wrote:
>> On 2013-02-01, Dombo <do...@disposable.invalid> wrote:
>>
>> > I recently participated in a review meeting about a coding standard to
>> > be used in that organization. They wanted a rule that required every
>> > function to be fully documented. Having been-there-and-done-that and
>> > having seen tons of pointless and misleading comments, my recommendation
>> > was to rewrite that rule to: don't write comments unless they have added
>> > value.
>>
>> And every time you find yourself about to write a comment stop and ask
>> yourself
>>
>> �Why is the code so unclear that it needs a comment?
>>
>> �Can I re-write this code so that its obvious what's going on without
>> �a comment?
>
>Oh you can ask yourself that once and learn to live with the
>obvious "no" answer for the rest of your life allright.
>
>Then get used to commenting your code well. In fact, how to comment
>code is something one has to learn the first year if not the first
>month when one begins to learn programming.
>Misleading people that comments can be unnecessary is one of the
>most counterproductive achievements of the high level languages
>last 2+ decades, its debilitating impact is to be carried with
>the industry for years if not decades - and who knows how much
>longer it will even stay as unnoticed as it is now.
>
>Uncommented code is just garbage.

True enough. I guess I read his questions more as asking, "Is
this specific comment appropriate and helpful?" and asking,
"Can I improve the code to make it clearer?" Not to the
exclusion of comments. But just to the overall improvement of
the net result of code+comments. I hadn't read it to say that
comments are to be eshewed. If he meant that, then I also
disagree flatly.

Jon

[Mel Wilson]

David Brown wrote:
[ ... ]

> However, systems like this are nothing more nor less than you can do
> with perfectly ordinary ASCII-based programming languages along with
> tools like doxygen (or javadoc, python docstrings, etc.). The only
> difference is that here you are in "documentation mode" by default and
> start "code mode" with some sort of delimiter - while with doxygen you
> are in "code mode" by default and start "documentation mode" by a
> specially formatted comment.

I was too elliptical. I was actually thinking about HTML as the markup
lanugage. I just forgot to say so.

Mel.

[dp]

That's a valid way of interpreting his comment, of course.
Quite likely the correct one, I just used his post as a
trigger for what I wrote.

Comments have more than one function when coding than making
the code easy to read years later - although this is the one
which makes them a must.
They tell the story; code is for machine consumption, comments
are for humans. When I write I put a comment on practically
every line which tells the story so one can understand what
(not how, with some exceptions) is being done by just reading
the comments. If it happens that I have difficulties making
the right comment I know it is for one of two reasons:
1) I am way too tired and no use anymore before I get enough sleep
and
2) I don't know what I am doing at the moment so I have to
stop writing and go into thinking mode, probably during a walk.

Knowing these two is really a time saver :-).

[Paul]

In article <kemoel$ulg$1...@dont-email.me>, mwi...@the-wire.com says...

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

[Ivan Shmakov]

>>>>> Paul <pa...@pcserviceselectronics.co.uk> writes:
>>>>> In article <kemoel$ulg$1...@dont-email.me>, mwi...@the-wire.com says...

[Cross-posting to news:comp.infosystems.www.misc.]

[On a second though, cross-posting to news:comp.lang.misc, too.]

[...]

>> I was too elliptical. I was actually thinking about HTML as the
>> markup lanugage. I just forgot to say so.

> 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.

[1] http://www.w3.org/TR/xhtml-modularization

--
FSF associate member #7257

[Paul]

In article <871ucwy...@violet.siamics.net>, onei...@gmail.com
says...

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 :-)

[dp]

On Feb 4, 6:21 pm, Paul <p...@pcserviceselectronics.co.uk> wrote:
> ...

>
> 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.

[John Devereux]

dp <d...@tgi-sci.com> writes:

> On Feb 4, 6:21 pm, Paul <p...@pcserviceselectronics.co.uk> wrote:
>> ...
>>
>> 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.

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 :)

--

John Devereux

[Roberto Waltman]

John Devereux wrote:
>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.
--
Roberto Waltman

[ Please reply to the group,
return address is invalid ]

[John Devereux]

Roberto Waltman <use...@rwaltman.com> writes:

> John Devereux wrote:
>>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...

But that is what doxygen et al already do AIUI.

> 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.

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.

[...]


--

John Devereux

[David Brown]

On 04/02/13 20:10, John Devereux wrote:
> dp <d...@tgi-sci.com> writes:
>
>> On Feb 4, 6:21 pm, Paul <p...@pcserviceselectronics.co.uk> wrote:
>>> ...
>>>
>>> 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.

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.

>
> 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 :)
>

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.)

[Jacob Sparre Andersen]

Vladimir Vassilevsky wrote:

> For great many reasons, it would be convenient to have source code in
> some rich format rather then plain ASC text. I could think of
> embedding illustrations, links and data into file, custom coloring,
> individual styles, comments, automatic macro expansion, presets and
> other features offered by modern word processors. The idea seems
> obvious; so there should be a tool for that already. That could be a
> pre-processor to import/export source text to/from some popular format
> such as *.doc or *.xml. Do you know of such tool ? Any comments?

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
--
"Computer Science is to Science, as Plumbing is to Hydrodynamics"

[Mel Wilson]

Jacob Sparre Andersen wrote:

> 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.

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.

[Stephen Pelc]

On Tue, 05 Feb 2013 17:06:33 +0100, Jacob Sparre Andersen
<spa...@nbi.dk> wrote:

>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.)

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

>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.

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.

[Stefan Reuther]

John Devereux wrote:
> 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.

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

[Walter Banks]

David Brown wrote:

> 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.

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.

> 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.

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..

[Hans-Bernhard Bröker]

On 05.02.2013 17:06, Jacob Sparre Andersen wrote:

> 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.

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.

[Lanarcam]

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

[Stefan Reuther]

Lanarcam wrote:

"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

[Lanarcam]

Le 06/02/2013 19:19, Stefan Reuther a �crit :

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.

[Jon Kirwan]

On Wed, 6 Feb 2013 06:13:15 -0800 (PST), Lanarcam
<lana...@yahoo.fr> wrote:

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

[dp]

On Feb 6, 8:19 pm, Stefan Reuther <stefan.n...@arcor.de> wrote:
> ....

> > 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

: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.

[Les Cargill]

I am seeing the tide go out from those approaches. Peaked about 2007ish.
YMMV. And I'll exclude "Matlab to 'C'" - that still happens.


--
Les Cargill

[Les Cargill]

Yep. All the CASE tool vendors go out of business otherwise.

--
Les Cargill

[Stefan Reuther]

Don't get me wrong. I'm totally for tools that validate the crap I code,
and if there were a domain-specific language to make that job easier, I
would use it. For one of our earlier products, I even wrote a program
that decompiled statemachines written in C into a model and verified its
consistency (our statemachine implementer had a very regular way of
formatting his source :-)

However, what I'm seeing now from the modelers is huge spaghetti state
machines nobody understands. The only advantage of those is that the
modelers can see that the device actually opens the MENU_SCREEN when the
"Menu" button is pressed in the OPENING_SCREEN by simulating the state
machine on a PC.

And then I'm seeing people who do not use language constructs that are
appropriate for solving a problem (like outlined above) because the
modeler won't let them. For another example, we have about a hundred
files like "VectorOfInt.hpp" that just contain a single typedef "typedef
std::vector<int> VectorOfInt;", because the modeling tool cannot handle
templates (but can be told "hey, there's a class 'VectorOfInt' in
<VectorOfInt.hpp>).

And all that makes code harder to understand and larger. In other words:
worse.

It may not be a problem when you're developing for a huge Java
application server. Code is too big? Add a few gigs of RAM. Code
crashes? Well, the user get's a HTTP 500 error and an exception dump,
but nothing dangerous. In embedded, I normally want to do better than that.


Stefan

[Przemek Klosowski]

On Thu, 31 Jan 2013 13:20:31 -0600, Vladimir Vassilevsky wrote:

> For great many reasons, it would be convenient to have source code in
> some rich format rather then plain ASC text. I could think of embedding
> illustrations, links and data into file, custom coloring, individual
> styles,
> comments, automatic macro expansion, presets and other features offered
> by modern word processors. The idea seems obvious; so there should be a
> tool for that already. That could be a pre-processor to import/export
> source text to/from some popular format such as *.doc or *.xml.
> Do you know of such tool ? Any comments?
>

Well, since you asked---there's the Literate Programming method, started
by the Great Don Knuth. There was a gaggle of Tangle/Weave systems for
original Pascal and then for Fortran, C, C++ and even some modular tools
that supported a wide variety. It was neat to be able to have one master
document that processed into LaTex and then PDF as well as into HTML, and
which generated all computer files as well: compilable source, Makefiles,
test harness and data. The tools understood the syntax, so they indexed
and hyperlinked the source.

My favorite feature, however, was the decoupling from the compiler
requirements. The master document defined chunks of code which were
subsequently reassembled for compilable source. Usually one defined
logically atomic chunks much shorter than a typical compilation unit;
such chunks could contain all related material in one place, including
source code, explanation with fancy TeX math, test data and harness, all
variable declarations and definitions, all in one logical place.

Needless to say it was too structured and never took the world by storm.
Doxygen is a pale shadow of the Literate Programming.

[Przemek Klosowski]

On Fri, 01 Feb 2013 11:05:39 -0800, Dave Nadler wrote:

> On Friday, February 1, 2013 10:30:40 AM UTC-5, Grant Edwards wrote:
>> The main problem with the output from Doxygen is that it's wrong.
>> The comments are wrong, therefore any output based on the comments is
>> wrong.
>>
>> OK, I'm being Hyperbolic, but I'd have to say that at least 80% of the
>> time, the Doxygen-generated docs for embedded stuff that I've come
>> across was worse than useless.
>
> I've certainly seen that too. Documentation has to be maintained
> (updated, reviewed) as a serious part of development rather than an
> afterthought.

or even better, documentation should BE the source code, as in Literate
programming (see my previous posting answering Vladimir's original query)