[erlang-questions] Erlang as a tool for human communication -- was GUI development
Fri Dec 22 13:33:30 CET 2017
(with what you ask?)
I could write a lot about this ...
The model of documentation I would like to see is:
- One author many eyes
Note this is not the wiki model - I like articles that are opinionated
a clear point of view - I may or may not agree with that point of
view, but I like there to be a clear point of view - books are written
by individual authors not committees and I like this.
Many eyes is great for fixing bugs and fact checking - so it should be
easy to comment on the document, but only the author can make the
- Beautiful output
The result should be pleasing to the eye and in multiple formats
(epub, html and PDF)
This is *impossible* (I think) with markdown - markdown solves the
Markdown solves the problem "make the input simple" it does not solve
"make the output beautiful"
LaTeX solves the problem "make the output beautiful" - but the input is a mess.
XSL + Apache FOP makes the input parsable but beautiful output is *challenging*
- Easy to organise the input
OK - the output should be beautiful - the input might be a mess (if In
LaTeX) - but moving chapter headings around etc and cross indexing etc
should be easy.
I have no good solution to this. My current attempt at this is to use
emacs org mode
for organisation. Then have embedded XML, and inside the XML and special tag
<md> ... </md> for embedded markdown (actually not the real markdown,
but my own variant)
- Low barrier for entry to comments
If a reader is reading the text and sees a spelling error, correcting
it should be one
mouse click away. The Erlang documentation requires you to git clone everything
fix the source and send a pull request. This is crazy and will scare
off many users.
The best system I have ever seen for this is in the real-world haskell site
Go check out http://book.realworldhaskell.org/read/ - pretend you have
seen a spelling
mistake and see how easy it is to fix it.
- Parseable document tree
I'm a great fan of having well-structured input that is parseable with
a strict grammar. This
is so we can build complex documents. This seems to rule out markdown and LaTeX.
My only solution to this XML - but *not* docbook (which is far too complex)
I want plugins to generate diagrams, color code etc.
Combining these different requirements (beautiful output, etc.) is
and I have seen no free system that can do all these things.
There are great tool chains available - for example when I wrote my Erlang book
the pragmatic press provided a tool chain.
The input was XML (Yes XML) - I have absolutely no problems with this,
most of my time
was spent in thinking up good examples and wording of paragraphs not typing in
The stages involved were
- editing (this was chapter by chapter with an editor providing feedback)
- beta release (publish a PDF - this is the many eyes bit)
- final chapters and more editing
- proof reading
- final edit
The author/editor part is interesting - this is not *many eyes* - each
book has an editor
who helps the author a lot (actually teaches them to write decent English)
Any automated system should have provision to automate the feedback cycles
author/editor and author/readers.
One more thing I forgot - who is your audience and what do they know.
Syncing with your audience is essential - If your book is 20 chapters
you need to write say
5 chapters, then try them out on your target audience to get the level
right and adjust the level *before* you write the next 15 chapters.
This is also true for a 10 page document.
I think the problem we have to solve here is one of making a documentation
*system* and not producing individual papers.
Short articles with ugly output is easy in markdown - but an entire system with
thousands of pages of text needs a lot of complex organisation.
I'd actually love to know how a newspaper solves this - a decent newspaper
turns out tens of thousands of words per day - news articles are
written, proof read and edited in hours - commissioned articles are
integrated with the news and there must be hundreds to thousands of
The software behind these systems is not open source and I haven't a
clue what it costs
or who produces it - is it in house or purchased?
I guess things of the scale of a magazine are done with adobe's indesign.
So we a spectrum of documents.
- simple documents (markdown)
- magazines (in-design)
- books (proprietary)
- newspaper (proprietary)
Where do we want to be positioned here? My guess is something 'book
like' is better than what we have today - but not commercial book
On Fri, Dec 22, 2017 at 7:03 AM, Lloyd R. Prentice
> This is a think piece that may run longer than prudent for this forum. But
> if not here, then where? It is motivated by the recent thread re: GUI
> development and various other threads re: Erlang documentation. It asks
> serious questions that may or may not be worthy of reflection and discussion
> across the Erlang community.
> Here's a little about me, not to toot my horn, but to clarify where I'm
> coming from.
> I've been striving to become reasonably proficient in Erlang for nearly four
> years now. I come with experience in software development, but in no way
> consider myself a professional programmer. My undergraduate education is in
> English language/liberal arts with a focus on creative writing;
> communication and national development was my focus in grad school. I was
> for seven years on the full-time faculty at Boston University's School for
> Public Communication. I was founding editor/publisher of Classroom Computer
> News, one of the first magazines focused on personal computers in the K-12
> classroom. My company. Prentice Associates Incorporated developed more than
> 100 shrink-wrapped educational/consumer software products for leading U.S.
> publishers. My company also developed a major web application for marketing
> and managing world-class IT conferences Among other things, I write fiction;
> have three novels in print. I could go on, but you get the picture.
> I come to Erlang with a vision of a web community devoted to helping indie
> authors/publishers write and market better books. I was attracted by the
> reliability/scalability promise of Erlang. But it's been a hard slog
> learning Erlang and bringing my vision to fruition, taking far longer than I
> would have hoped, leavened only by the generous help from many members of
> this community.
> At this point, my understanding is that Erlang is a terrific language for
> distributed back-end systems and, to some extent, scalable web applications.
> But my sense is that the Erlang community is smaller than the merits of the
> language deserves, has an aging community and, rather than organic growth,
> seems to be fragmenting into a cluster of BEAM languages that don't, from
> what I've seen, bring much vitality back to Erlang OTP.
> The question I've asked myself over recent months is, "Why doesn't Erlang
> have more libraries supporting human communication with the same
> effectiveness with which it supports machine-to-machine communication?"
> The recent thread GUI development thread is Exhibit Number One.
> The various stalemated Erlang-questions threads on Erlang documentation is
> Exhibit Number Two.
> Loïc Hoguin has done some nice work on documentation tools. I do wish they
> were more widely used and, themselves, better documented.
> This makes me wonder why we don't eat our own dog food, that is, develop and
> adopt standardized documentation tools written in Erlang and fluent across
> all media?
> Wings3D is, from what I've read, an effective 3D CAD system. But I don't
> hear much about it or see how it's libraries or components are of value to
> the Erlang community. Perhaps there are hidden jewels in the Wings3D code
> that could support GUI development.
> Joe Armstrong has been experimenting with music production. I love to see
> more documentation of his work. Can his work be extended to broader audio
> A few folks have been working with video streaming. Wouldn't it be great to
> see tutorials and well-documented open source libraries and tools.
> Erlang Nitrogen goes a long way toward easing the pains of web development.
> But it could go much further with broader support. These days, poor Jesse
> Gumm is just about it.
> I'm not sure what's going on with Chicago Boss. That seems to be on Jesse's
> shoulders as well.
> The content management framework Zotonic is terrific in every dimension. But
> you have to move out of Erlang and to hop across several syntactic
> boundaries to use it. Mark Worrell has been talking for some time about
> "Elastic Zotonic," e.g. distributed Zotonic. Is he thinking Riak? I don't
> know, but wouldn't that be cool.
> I've been pulling my hair out over the past year trying to bend erlguten,
> the not-well-documented six-year-old library for generating PDF documents,
> to my needs. It's a gem in the rough that could provide the basis for a
> powerful suite of print and digital media production tools.
> Just today I learned that erlguten has been maintained and in production at
> Klarna and that within the past year Richard Carlsson has released a
> MIT-licensed "canonical" version on GitHub. Yippee!
> Richard's road map is dead congruent with what I've been trying to
> accomplish in support of Writersglen, the project that has absorbed my
> nearly every waking thought over the past half decade.
> Many of the things that I want to do in Writersglen could be accomplished in
> other languages and with tools and applications written in those languages.
> But I want to work in Erlang. I don't see any technical obstacles to
> building better human communication libraries and tools in Erlang.
> Selfishly, I don't have enough years ahead to learn other languages. I want
> to build my web community. I want to build it in Erlang. And I wish I'd been
> able to launch it two years ago.
> But beyond my own interests, my hypothesis is this: With more
> well-documented and polished open source libraries and applications focused
> on human communication, Erlang would attract a wider, more diverse,
> population of programmers and developers. This, in turn, would result in a
> more vibrant community and wider adoption of Erlang.
> Am I wrong?
> If not, what can we do to make it happen?
> Perhaps the problem is that we don't have an appropriate venue or forum for
> sharing ideas.
> All the best and happy holidays,
> Sent from my iPad
> erlang-questions mailing list
More information about the erlang-questions