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.
