On 21/09/16 20:56, Waldek Hebisch wrote:
Martin Baker wrote:
Usually I first produce documentation in HTML and put it on my website.
I then copy it into code file, this copy is inferior to the HTML version
because it does not have diagrams.

What do you use to create diagrams?  In other words: what is the
sorce code of your diagrams?

I use an open source program called Inkscape. It stores the diagrams in SVG (which is an XML format) so I suppose you could say that is the source but I don't edit it with a text editor. Because different browsers can render SVG slightly differently I tend to export to a raster format (PNG) for the web. I think this is as standards based as I can get.

Some of the diagrams can be quite big, too big for HyperDoc sized windows I think.

Well, I prefer to be independent of network if possible.
Network have unpredictable performance, may be not available
at all.  There are also securtity problems which vanish
if tere is no network connection.  So it good to have
standalone documentation.

Also we want documentation to be secure for the long term, that is, we don't want so documentation to disappear if an individual developer stops working on it or for a tool chain to become unmaintainable if an individual company goes bust.

There must be some way that web documents could optionally be distributed with the code for use offline if required.

Another aspect is conceptual and technical integrity.
Online documentation fits well to distributed/decentralized
model where various pieces are developed independently.
This has advantages, allowing various approches and
creating diverse points of view.  But it also leads to
replication and bloat.  And it makes harder to find
relevant correct documentation.

From my point of view, its not very easy to find the correct documentation now, that’s why I would like a central hub which I think Fricas IO has the potential to become.

So it makes sense to
develop core documentation in more coordinated way,
trying to use common style and common tools.
Unfortunately, in the past it was hard to reach
agreement what the common approach should be.

Exactly, if there are n people reading this then there will be n different views about what the common approach should be.

Your comments are a very good summary of the various sources of documentation and how they evolved. It is easy to see that each has its pros and cons. I think I'm reluctantly coming to the conclusion that there is not likely to be consensus on this any time soon.

IMO ability to produce different renderings (versions)
of documentation is important.

Yes, and I expect different formats can be produced from hyperdoc at the syntax level. But once a document has been chopped up into small windows I think its usefulness and readability will be greatly diminished when concatinated back to HTML or other formats.

When documenting precisely defined mathematical structures then it might be a good idea to force authors to be concise and fit everything into a small window. However with graphics related software there is a lot of explanation required and a limit to how much this can be compressed down.

Even with mathematical structures like SimplicialComplex for example there are a lot of arbitrary decisions which need to be explained in a lot of detail which would be very hard to cram into small windows. By "arbitrary decisions" I mean choices about notation, representation, user interface, etc. that is not forced by the underlying mathematics.

I will try to convert
parts of your documentation to HyperDoc, we will see
how it works.

Please please don't. I sent the earlier post because I thought there might be a way to cut down on everyones work but that would just increase the workload. I would feel very guilty if I caused you extra work doing this. I think it would be better to stay with the current situation than to go down that path.

I think there are situations where the small guys can beat the big guys but I think the battles have to be chosen carefully. I'm not sure competing with web tools is winnable especially since documentation tools are not the core business of FriCAS.

Martin B

You received this message because you are subscribed to the Google Groups "FriCAS - 
computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to fricas-devel+unsubscr...@googlegroups.com.
To post to this group, send email to fricas-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.

Reply via email to