Smalltalk › Pharo › Pharo Smalltalk Developers

Improving the documentation model

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

32 messages Options

Stephan Eggermont-3

Improving the documentation model

TL;DR: Some roadmap ideas. Looks like a lot of work.
Comments and improvements welcome:
We should replace the Pillar document format
by a better one, suitable for WYSIWYG editing and
creating long documents.

---

The current documentation model for Pharo is Pillar.
Pillar is the document model from the Pier CMS and
provides exports to (a.o) html and LaTeX. It is a
simplified form of the LaTeX document model
without a WYSIWYG UI.

In the research world two documentation systems
dominate: LaTeX and Word. Word and its clones
dominate areas where ease of use for small papers
without maths are important, LaTeX the other fields.

From personal experience I know that the lack of
abstraction in Word and clones makes it very expensive
to create large, consistently formatted documents.
In addition, the typographical quality of the resulting
documents is much lower than that achievable with
LaTeX.

On the other hand, repurposing LaTeX to generate
anything other than PDF/paper documentation is
difficult because of the underlying language that
LaTeX is written in, and there is no easy to use
WYSIWYG UI for LaTeX.

It pains me to see the return of text based formatting
with primitive formats like markdown. At least in LaTeX
you can preserve semantics level content, in markdown
we are back at html 1.0.

The program I liked best for creating longer documents
was Framemaker. That provided the needed abstractions
in an efficient WYSIWYG UI. Framemaker was sold
from 1986, so the performance of current hardware
should be enough to run something similar in smalltalk.
I used versions 5.5 and 6, and had to abandon it when
Adobe stopped development and it was never migrated
from PowerPC.

Framemaker was fast enough to create books with
hundreds and even thousands of pages. It had working
versions of the long document features Word claimed to
have.

With Athens and TxText we now have low level
abstractions for dealing with cursor and selection, fonts,
rendering glyphs and having both on-screen and
PDF output.

On top of TxText we could add a model somewhat like
the attached figure
UML diagram of document structure

A book consists of a number of named documents.
This is essential for dealing with longer material, as
in a wysiwyg system we want to avoid having to re-layout
too much after a key is pressed. Across documents we only
need to remember the starting page/section numbers.

Each document consists of pages. On a page there can be fixed
content and content that is dependent on the text flow.
Most pages of a document have a similar layout, so each page
refers to a masterpage that defines the default content.
A document can have separate masterpages for
first, left and right pages, and rotated or extra large ones.
A masterpage can define fixed items and calculated ones
(pagenumbers and current chapter). A textframedefinition
describes the textframes and the textflow for each textframe.

The text (and other in-line contents) of the document are stored
in paragraphs, which are stored in textflows.
The paragraphstyle of a paragraph knows how to layout it in
a textframe, and how to deal with the end of a textframe.
The paragraphstyle knows how to paginate, how to number
or provide other autotext at the beginning of a paragraph and
if the paragraph text should be part of a table of contents.
A textframe is a (rectangular) area on a page.
The characterstyle of a paragraph is responsible for the font family,
size and style. The characterstyle can be overridden
by a specific paragraph or by a textrange.

With a model like this (and adding maths, tables, notes, figures
and references) we should be able to use Pharo to create both
high-quality documentation, and write research articles
(and books) in-image.

Stephan

Damien Cassou-2

Re: Improving the documentation model

stephan <[hidden email]> writes:

> TL;DR: Some roadmap ideas. Looks like a lot of work.
> Comments and improvements welcome:
> We should replace the Pillar document format
> by a better one, suitable for WYSIWYG editing and
> creating long documents.

I agree that Pillar is far from perfect. Do you propose to (1) start
something from scratch or to (2) improve Pillar? If you propose (1), how
much do you plan to spend each day and for how long before reaching
Pillar current's state? If you propose (2), you can start doing
something small today and finish the same day. With (2) you could
improve the current situation before we go to bed.

--
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

Ralph Boland

Re: Improving the documentation model

In reply to this post by Stephan Eggermont-3

...
> and there is no easy to use WYSIWYG UI for LaTeX.
...

Why is Lyx not an easy to use WYSIWYG UI for LaTeX.

Ralph Boland

Dmitri Zagidulin

Re: Improving the documentation model

In reply to this post by Stephan Eggermont-3

I strongly believe that the WYSIWYG editing route is a fundamentally worse approach for documentation (and textbooks) than text-based formatting such as Pillar, Markdown and Asciidoc.

Specifically, it will result in less community contribution, and it will make distributed version control of documents much harder.

That said, I will support whatever documentation format or tech stack that the community adapts. Any documentation is better than none, regardless of the underlying details. (Though I will always advocate for text-based formats).

Instead of going the route that you propose (which essentially attempts to Word or Google Docs in-image), I think we should:

* Extend Pillar. With a few more features, it can be on par with Markdown and Asciidoc, and then eventually surpass it (and have nice Pharo-specific features like detection and unit-testing of Pharo code blocks, etc).

* Invest in instant-preview tech, in-image. This is similar to what PillarHub does, for example, by using the Ace online editor. Take a look at the first screenshot in: http://pillarhub.pharocloud.com/hub/pillarhub/about

Side-by-side instant preview makes it possible to have the best of both worlds, text-based markup and WYSIWYG, without the typical WYSIWYG drawbacks (of making distributed version control difficult, first and foremost).

I will attempt to explain my reasoning, both for text-based markup, and against heavier WYSIWYG approaches.

1) With documentation (and textbooks), the number one goal and number one virtue is: make it easy for people to contibute. This means two things -- the simplicity of the format (this is where LaTeX fails), and the ease of distributed version control (merging, pull requests, reviews and commentary on contributions).

Look at the explosion in community-generated documentation and content (READMEs on repos, the entirety of Wikipedia) that has resulted from *making it easy for people to contribute and edit collaboratively*.

2) Version control, especially with more than one or two collaborators, is a *nightmare* with WYSIWYG tools. Look at what the state of the art is, at what Microsoft's Word and Google's Docs have been able to accomplish, in terms of revision control.

Despite unimaginable amounts of person-hours of development put into it, it's pretty much unusable (I speak from extensive personal experience, both from collaborating on technical and business documents using Word and Docs, and from seeing my wife and her friends (who are professional authors) struggle with Word's revision control systems while working with their publishers).

We are not Microsoft or Google. We are not going to solve the WYSIWYG source control / version control problem better than they are. We need to focus where we spend our efforts. In contrast, text-based markup version control is a solved problem.

3) The convenience of WYSIWYG can be provided with side-by-side instant preview (again, see PillarHub and the numerous WYSIWYG instant-previews in Markdown editors).

4) The ability to render source text-based markup into multiple formats (PDF, HTML, etc), is *essential*. Going from WYSIWYG to HTML is impossible (all attempts to do so, by Microsoft, Adobe, etc, have utterly failed). Whereas going from text-based to print/PDF is very doable (see LaTeX, the entirety of HTML ecosystem, Pillar, etc).

This is a serious problem that FrameMaker never had to solve.

5) Text-based markup is not primitive. You mention a comparison to HTML 1.0. This is apt, but in the opposite direction than you intend. 1.0 may have been primitive. But it has evolved into HTML 5, which not only has many semantics level content features, but is expressive enough that pretty much all UIs are moving to it (operating systems, desktop app suites, mobile devices, etc).

Pillar may be in a primitive state right now, but it already has some decent semantics-level capability, and can have a lot more with considerably less effort than it would take to evolve WYSIWYG tools.

And actually, the WYSIWYG approach is much closer to HTML 1.0 (in the sense that, users have to indicate *semantic* intentions like emphasis by selecting different fonts, versus something like HTML 4/5, where the actual intention is declared (EMPH tags, QUOTE tags, etc).

6) You mention the two standards in document writing (Word and LaTeX), and the drawbacks to each. I completely agree there. There is a third option, however, on which the world of open-source community technical writing is standardizing. And it involves text-based markup languages:

* Markdown (in the form of https://www.gitbook.com/ )

* Asciidoc (more specifically, the Asciidoctor http://asciidoctor.org/ text processor and publishing toolchain). Take a look at https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272 for example.

* Pillar (that's us).

7) Text-based markup formats (aside from LaTeX) actually possess all of the desired features that you mention, that are required to write book-length technical documentations. Something like Asciidoc already possesses them, and Pillar has most of them (and can be extended to have the rest).

Let's take a look at some of them:

* High-level publishing-centered semantic abstractions. In other words, both the concept of book sections, chapters, chapter sections, paragraphs, figures, etc, as well as the ability to compose a larger document out of smaller named documents:

- Pillar and Asciidoc have chapters, sections, paragraphs, figures and named scripts/code blocks.

- Asciidoc has the ability to do file imports (compose a larger document out of smaller docs)

* Links. Asciidoc has semantic links both within a document, and across different Asciidoc documents (references to chapters, sections, etc). Pillar has within-document links, and inter-doc links are on the roadmap.

* The ability to drop down to a more expressive markup (LaTeX or HTML). For heavier-duty features like formulas and equations, all of the simple markup languages allow the author to drop down to LaTeX and lay out formulas to their heart's content.

8) Text-based markup formats are much easier to both extend (add new semantic tags, etc) and to machine-process (parse, apply macros, etc) than WYSIWYG formats.

So, in summary:

- Text-based markup languages result in a lot more technical docs being written

- Pillar can match or beat any of the WYSIWYG editor features, with not too much time and effort investment.

On Tue, Apr 21, 2015 at 9:11 AM, stephan <[hidden email]> wrote:

TL;DR: Some roadmap ideas. Looks like a lot of work.
Comments and improvements welcome:
We should replace the Pillar document format
by a better one, suitable for WYSIWYG editing and
creating long documents.

---

The current documentation model for Pharo is Pillar.
Pillar is the document model from the Pier CMS and
provides exports to (a.o) html and LaTeX. It is a
simplified form of the LaTeX document model
without a WYSIWYG UI.

In the research world two documentation systems
dominate: LaTeX and Word. Word and its clones
dominate areas where ease of use for small papers
without maths are important, LaTeX the other fields.

From personal experience I know that the lack of
abstraction in Word and clones makes it very expensive
to create large, consistently formatted documents.
In addition, the typographical quality of the resulting
documents is much lower than that achievable with
LaTeX.

On the other hand, repurposing LaTeX to generate
anything other than PDF/paper documentation is
difficult because of the underlying language that
LaTeX is written in, and there is no easy to use
WYSIWYG UI for LaTeX.

It pains me to see the return of text based formatting
with primitive formats like markdown. At least in LaTeX
you can preserve semantics level content, in markdown
we are back at html 1.0.

The program I liked best for creating longer documents
was Framemaker. That provided the needed abstractions
in an efficient WYSIWYG UI. Framemaker was sold
from 1986, so the performance of current hardware
should be enough to run something similar in smalltalk.
I used versions 5.5 and 6, and had to abandon it when
Adobe stopped development and it was never migrated
from PowerPC.

Framemaker was fast enough to create books with
hundreds and even thousands of pages. It had working
versions of the long document features Word claimed to
have.

With Athens and TxText we now have low level
abstractions for dealing with cursor and selection, fonts,
rendering glyphs and having both on-screen and
PDF output.

On top of TxText we could add a model somewhat like
the attached figure

A book consists of a number of named documents.
This is essential for dealing with longer material, as
in a wysiwyg system we want to avoid having to re-layout
too much after a key is pressed. Across documents we only
need to remember the starting page/section numbers.

Each document consists of pages. On a page there can be fixed
content and content that is dependent on the text flow.
Most pages of a document have a similar layout, so each page
refers to a masterpage that defines the default content.
A document can have separate masterpages for
first, left and right pages, and rotated or extra large ones.
A masterpage can define fixed items and calculated ones
(pagenumbers and current chapter). A textframedefinition
describes the textframes and the textflow for each textframe.

The text (and other in-line contents) of the document are stored
in paragraphs, which are stored in textflows.
The paragraphstyle of a paragraph knows how to layout it in
a textframe, and how to deal with the end of a textframe.
The paragraphstyle knows how to paginate, how to number
or provide other autotext at the beginning of a paragraph and
if the paragraph text should be part of a table of contents.
A textframe is a (rectangular) area on a page.
The characterstyle of a paragraph is responsible for the font family,
size and style. The characterstyle can be overridden
by a specific paragraph or by a textrange.

With a model like this (and adding maths, tables, notes, figures
and references) we should be able to use Pharo to create both
high-quality documentation, and write research articles
(and books) in-image.

Stephan

Sean P. DeNigris

Re: Improving the documentation model

Administrator

In reply to this post by Stephan Eggermont-3

Stephan Eggermont wrote

We should replace the Pillar document format
by a better one, suitable for WYSIWYG editing and
creating long documents.

I dream that all documents in my Dynabook are WYSIWYG. However, the computing world seems to have regressed into writing documents in various forms of assembly code. I'd love to have what you are suggesting, but there is too much time, energy, and most importantly emotion invested in Pillar to convince a change. IMHO, the only course would be to collect the people who agree with you, create what you are proposing on your own, and deliver it to the community to see for themselves why it is a better way.

Cheers,
Sean

Dmitri Zagidulin

Re: Improving the documentation model

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:

I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

kilon.alios

Re: Improving the documentation model

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

nacho

Re: Improving the documentation model

The other day I was thinking about this. I thought that it would be a great idea to have a pillar rendering engine inside Pharo.

In that way the documentation written will be available in the image WYSIWYG with no need for recompilation. The update of books will be easy, just do a Software Update and the documentation is up to date.

a Pillar rendering, WYSIWYG editor would be great.

cheers

Nacho

Lic. Ignacio Sniechowski, MBA

Prosavic SRL

Tel: (011) 4542-6714

On Tue, Apr 21, 2015 at 2:49 PM, kilon.alios [via Smalltalk] <[hidden email]> wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

If you reply to this email, your message will be added to the discussion below:
http://forum.world.st/Improving-the-documentation-model-tp4820814p4820973.html

To start a new topic under Pharo Smalltalk Developers, email [hidden email]
To unsubscribe from Pharo Smalltalk Developers, click here.
NAML

Nacho Smalltalker apprentice. Buenos Aires, Argentina.

philippeback

Re: Improving the documentation model

In reply to this post by kilon.alios

Pillar is fine as long as we aren't forced into the backend quirks to get a given output.

I haven't see Docbook and Docbook-XML and XSL-FO mentioned. But these are working nicely too.

Lots of Linux docs are written with Docbook.

I've a client who outputs supercomplicated documents with XSL-FO.

A Pillar output to Docbook would be great.

One must invest time in any choice to be really productive. WYSIWYG included.

FWIW LibreOffice equations are written much faster when one knows the text based language than with the point and click tools.

The best thing is an ability to render fast. Same as Smalltalk: fast feedback in order to iterate without a break in the flow.

Le 21 avr. 2015 20:03, "kilon alios" <[hidden email]> a écrit :

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

Nicolas Anquetil

Re: Improving the documentation model

In reply to this post by kilon.alios

This remind me of a discussion a very long time ago on a newsgroup

- a young zealot of GUI (windows, buttons, mouses) was asking himself and the community how people could deny that this was the best interface on earth or how anybody could prefer text based interface

- a seasonned sys. admin then started to explain all the clicks he had to perform to create one new user account. Result: for one new user some minutes of work
He then added that he had to create HUMDREDS of user every year and was so very happy that he did not had to do it all by pointing and clicking but had some scripts to do it.

So the answer to all this is that there are very good and valid reasons to prefer text to all the shiny interfaces of he world.
And you don't even have to look very far to find some.

As for programming with in a graphical way, the ability has been around for decades.
I believe we can safely assume that if people are still using textual interface after such a very long period (in computer science time frame), it is most certainly because natural selection has favoured the choice that had most advantages ...

nicolas

PS: which does not mean that GUI are completely useless

On 21/04/2015 20:03, kilon alios wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

philippeback

Re: Improving the documentation model

On Tue, Apr 21, 2015 at 8:48 PM, Nicolas Anquetil <[hidden email]> wrote:

This remind me of a discussion a very long time ago on a newsgroup

- a young zealot of GUI (windows, buttons, mouses) was asking himself and the community how people could deny that this was the best interface on earth or how anybody could prefer text based interface

- a seasonned sys. admin then started to explain all the clicks he had to perform to create one new user account. Result: for one new user some minutes of work
He then added that he had to create HUMDREDS of user every year and was so very happy that he did not had to do it all by pointing and clicking but had some scripts to do it.

So the answer to all this is that there are very good and valid reasons to prefer text to all the shiny interfaces of he world.
And you don't even have to look very far to find some.

As for programming with in a graphical way, the ability has been around for decades.
I believe we can safely assume that if people are still using textual interface after such a very long period (in computer science time frame), it is most certainly because natural selection has favoured the choice that had most advantages ...

Coral, where are you?

nicolas

PS: which does not mean that GUI are completely useless

On 21/04/2015 20:03, kilon alios wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

kilon.alios

Re: Improving the documentation model

In reply to this post by Nicolas Anquetil

Its funny you mention natural selection an extremely stupid and slow process. Fortunately for us software evolves with artificial selection which way faster and way more intelligent. But still it comes with a great deal of flaws when you take a look at what exactly is popular in the coding world nowdays . Or even outside the coding world. But yes we can sit here and debate this for million of years.

I am not a GUI zealot though, I have my own opinion that I never try to enforce on others. I am perfectly ok with people that prefer a text based approach. The only thing I am saying that GUIs have one undisputed advantage, they are not text based only ;)

For me it comes down to making sensible convenient and practical useful UIs. How you do it , graphical or text based is secondary concern.

I am also aware of the fact that GUIs tend to be more difficult to create, which provides a very good explanation why command lines are still quite popular.

On Tue, Apr 21, 2015 at 9:48 PM, Nicolas Anquetil <[hidden email]> wrote:

This remind me of a discussion a very long time ago on a newsgroup

- a young zealot of GUI (windows, buttons, mouses) was asking himself and the community how people could deny that this was the best interface on earth or how anybody could prefer text based interface

- a seasonned sys. admin then started to explain all the clicks he had to perform to create one new user account. Result: for one new user some minutes of work
He then added that he had to create HUMDREDS of user every year and was so very happy that he did not had to do it all by pointing and clicking but had some scripts to do it.

So the answer to all this is that there are very good and valid reasons to prefer text to all the shiny interfaces of he world.
And you don't even have to look very far to find some.

As for programming with in a graphical way, the ability has been around for decades.
I believe we can safely assume that if people are still using textual interface after such a very long period (in computer science time frame), it is most certainly because natural selection has favoured the choice that had most advantages ...

nicolas

PS: which does not mean that GUI are completely useless

On 21/04/2015 20:03, kilon alios wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

nacho

Re: Improving the documentation model

I think we have to distinguish two things.

One thing is GUI only with mouse. Another one is GUI with lots of keyboard shortcuts and bindings.

For instance. I use a lot of Excel which clearly is a GUI app but I seldom use the mouse it is much productive for me to use shortcuts.

An analogy can be made between Python an Pharo.

Python is great, but one of the things that really annoys me is that all the methods, clases are there in a way which is difficult to grasp them. On the other hand, the System Browser is a wonderful thing for an OO language.

GUI Zealot yes, mouse Zealot definitely not.

Cheers

Nacho

Lic. Ignacio Sniechowski, MBA

Prosavic SRL

Tel: (011) 4542-6714

On Tue, Apr 21, 2015 at 4:35 PM, kilon.alios [via Smalltalk] <[hidden email]> wrote:

Its funny you mention natural selection an extremely stupid and slow process. Fortunately for us software evolves with artificial selection which way faster and way more intelligent. But still it comes with a great deal of flaws when you take a look at what exactly is popular in the coding world nowdays . Or even outside the coding world. But yes we can sit here and debate this for million of years.

I am not a GUI zealot though, I have my own opinion that I never try to enforce on others. I am perfectly ok with people that prefer a text based approach. The only thing I am saying that GUIs have one undisputed advantage, they are not text based only ;)

For me it comes down to making sensible convenient and practical useful UIs. How you do it , graphical or text based is secondary concern.

I am also aware of the fact that GUIs tend to be more difficult to create, which provides a very good explanation why command lines are still quite popular.

On Tue, Apr 21, 2015 at 9:48 PM, Nicolas Anquetil <[hidden email]> wrote:

This remind me of a discussion a very long time ago on a newsgroup

- a young zealot of GUI (windows, buttons, mouses) was asking himself and the community how people could deny that this was the best interface on earth or how anybody could prefer text based interface

- a seasonned sys. admin then started to explain all the clicks he had to perform to create one new user account. Result: for one new user some minutes of work
He then added that he had to create HUMDREDS of user every year and was so very happy that he did not had to do it all by pointing and clicking but had some scripts to do it.

So the answer to all this is that there are very good and valid reasons to prefer text to all the shiny interfaces of he world.
And you don't even have to look very far to find some.

As for programming with in a graphical way, the ability has been around for decades.
I believe we can safely assume that if people are still using textual interface after such a very long period (in computer science time frame), it is most certainly because natural selection has favoured the choice that had most advantages ...

nicolas

PS: which does not mean that GUI are completely useless

On 21/04/2015 20:03, kilon alios wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

If you reply to this email, your message will be added to the discussion below:
http://forum.world.st/Improving-the-documentation-model-tp4820814p4820989.html

To start a new topic under Pharo Smalltalk Developers, email [hidden email]
To unsubscribe from Pharo Smalltalk Developers, click here.
NAML

Nacho Smalltalker apprentice. Buenos Aires, Argentina.

Dmitri Zagidulin

Re: Improving the documentation model

In reply to this post by kilon.alios

And just to be clear, I am not against GUIs, specifically.

I'm against GUIs for distributed version control for collaborating on documentation.

And only because I haven't seen it done in a usable fashion (again, see Revision Control in Word or Google Docs). I'm always willing to be proven wrong on that count, if some amazing tech comes along.

On Tue, Apr 21, 2015 at 3:48 PM, kilon alios <[hidden email]> wrote:

Its funny you mention natural selection an extremely stupid and slow process. Fortunately for us software evolves with artificial selection which way faster and way more intelligent. But still it comes with a great deal of flaws when you take a look at what exactly is popular in the coding world nowdays . Or even outside the coding world. But yes we can sit here and debate this for million of years.

I am not a GUI zealot though, I have my own opinion that I never try to enforce on others. I am perfectly ok with people that prefer a text based approach. The only thing I am saying that GUIs have one undisputed advantage, they are not text based only ;)

For me it comes down to making sensible convenient and practical useful UIs. How you do it , graphical or text based is secondary concern.

I am also aware of the fact that GUIs tend to be more difficult to create, which provides a very good explanation why command lines are still quite popular.

On Tue, Apr 21, 2015 at 9:48 PM, Nicolas Anquetil <[hidden email]> wrote:

This remind me of a discussion a very long time ago on a newsgroup

- a young zealot of GUI (windows, buttons, mouses) was asking himself and the community how people could deny that this was the best interface on earth or how anybody could prefer text based interface

- a seasonned sys. admin then started to explain all the clicks he had to perform to create one new user account. Result: for one new user some minutes of work
He then added that he had to create HUMDREDS of user every year and was so very happy that he did not had to do it all by pointing and clicking but had some scripts to do it.

So the answer to all this is that there are very good and valid reasons to prefer text to all the shiny interfaces of he world.
And you don't even have to look very far to find some.

As for programming with in a graphical way, the ability has been around for decades.
I believe we can safely assume that if people are still using textual interface after such a very long period (in computer science time frame), it is most certainly because natural selection has favoured the choice that had most advantages ...

nicolas

PS: which does not mean that GUI are completely useless

On 21/04/2015 20:03, kilon alios wrote:

Funnily enough I am in the exact opposite opinion, of Graphical approach being vastly superior to text based approach including programming languages. 25 years using computers and coding with them and still cannot fathom why programming languages are still a think and why developers and "power" users rely so much on text based approach. But whether I like it or not the coding world is dominated by text based solutions.

Its a pointless debate though when it comes to pharo will depend on the people doing the work. Personally I don't have the time of going very deep into this and doing all the hard work it requires. My focus is elsewhere. But I welcome any contribution.

As a lawyer myself and a coder, I cannot even begin to compare Latex to the convenience of Libreoffice I use at work. Its not even a debate . Latex is something I never heard of until Pillar introduced me to it. Can't imagine who in the right mind would use this to document things, but I guess they have their reasons.

I started with command line and CP/M back in 1988 but even back then when GUIs were not mainstream (at least in my country) I was dreaming of graphical intefaces that would lift me from the restrictions of text based approach and the dreaded command line. I wish I had found out about Smalltalk back then and its elegant solution to this problem.

I love Pillar because its simple and I like the syntax, but yeah in the end I would choose a Graphical Documentation Tool no questions asked.

On Tue, Apr 21, 2015 at 7:39 PM, Dmitri Zagidulin <[hidden email]> wrote:

On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email]> wrote:
I dream that all documents in my Dynabook are WYSIWYG. However, the
computing world seems to have regressed into writing documents in various
forms of assembly code.

Completely disagree, that it's a regression in any way :) Text-based document writing has enabled so many more features than WYSIWYG approaches have ever dreamed of. I would be happy to debate the merits of the two approaches, feature-for-feature.

You're basically pining for the equivalent of VisualBasic drag & drop programming, versus the flexibility of writing code in an editor. The latter wins, no contest. (Now, that is not to say that text-based code editing can't be /improved/ with better IDE tools, that's what we're all about after all.)

kilon.alios

Re: Improving the documentation model

"I'm against GUIs for distributed version control for collaborating on documentation. "

yes this is a valid concern this is why I also agree with what others have said of a GUI toll that helps us write documentation but it exports it to pillar so we can use easily version control with it. Or maybe you mean you are not satisfied with how git gui clients have been doing their job ?

"GUI Zealot yes, mouse Zealot definitely not."

Yeap I agree with this very much, I am using a 3d application, Blender and as you can imagine relying on mouse is basically unthinkable because of how extremely complex the UI is. I use mouse for editing polygons, I use a wacom tablet for sculpting and I use keyboard shorcuts for ton of other blender actions. 3d apps have ton of shortcuts out of necessity. But there is a solution recently in the form of pie penus, those menus work on premise of leaving an open circle area for displaying what you operate on and open around it icon based menus in circular layout. You can enter those menus using mouse gestures (you can also optionally do it the traditional way of clicking on the menus), that makes for very fast interaction as fast as using key shortcuts. You can this way create mouse gesture combos to do very complex actions and at the same time you have a visual feedback of what you doing exactly something that shortcus lack. Those mouse gestures dont require any clicking.

I think pie menus would work great for Pharo.

So there is a lot of room for UI ideas still and GUIs are still in an infant state. Another idea I had recently it using a multi touch device like smartphone or table as an interface used for operating Blender and Pharo, something like a TV remote . This usage is popular with musicians for controlling musical software.

Sean P. DeNigris

Re: Improving the documentation model

Administrator

In reply to this post by Nicolas Anquetil

Nicolas Anquetil wrote

I believe we can safely assume that if people are still using textual
interface after such a very long period (in computer science time
frame), it is most certainly because natural selection has favoured the
choice that had most advantages ...

By this rationale, we should all stop programming Smalltalk immediately in favor of COBOL ;)

Cheers,
Sean

Sean P. DeNigris

Re: Improving the documentation model

Administrator

In reply to this post by philippeback

philippeback wrote

Pillar is fine as long as we aren't forced into the backend quirks to get a
given output.

This is actually much more productive than I thought it would be :) We've identified some key intentions:
- easy to version
- easy to contribute
- live (whether preview rendering or model being worked on)
- portable (to other formats); i.e. not tied to one backend; I would add here that any syntax is just a serialized, dead form of the live model, which is what I really want to think about
- easy to use for beginners (like WYSIWYG, live help)
- pathway to efficient use for experts (a la command line, shortcuts, gestures; not mouse selection)

That's a really great list. And WYSIWYG and Pillar are two different explorations into that problem space. But there is no point trying to convince through words, only to produce your favored approach that adresses those points more effectively than the other approach, or maybe we end up with two amazing approaches, like emacs and vim and we can happily debate forever ;)

Cheers,
Sean

kilon.alios

Re: Improving the documentation model

for the record this is something I am interested into contributing. It would be great if we coordinate effort . I don't make big promises but I can definitely spare some hours or even days. I am in the process of documenting Morphic and I definitely want something more interactive something more Pharo ;)

On Wed, Apr 22, 2015 at 12:01 AM Sean P. DeNigris <[hidden email]> wrote:

philippeback wrote
> Pillar is fine as long as we aren't forced into the backend quirks to get
> a
> given output.

This is actually much more productive than I thought it would be :) We've
identified some key intentions:
- easy to version
- easy to contribute
- live (whether preview rendering or model being worked on)
- portable (to other formats); i.e. not tied to one backend; I would add
here that any syntax is just a serialized, dead form of the live model,
which is what I really want to think about
- easy to use for beginners (like WYSIWYG, live help)
- pathway to efficient use for experts (a la command line, shortcuts,
gestures; not mouse selection)

That's a really great list. And WYSIWYG and Pillar are two different
explorations into that problem space. But there is no point trying to
convince through words, only to produce your favored approach that adresses
those points more effectively than the other approach, or maybe we end up
with two amazing approaches, like emacs and vim and we can happily debate
forever ;)

-----
Cheers,
Sean
--
View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4821009.html
Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.

Stephan Eggermont-3

Re: Improving the documentation model

In reply to this post by Damien Cassou-2

On 21/04/15 17:59, Damien Cassou wrote:

>
> stephan <[hidden email]> writes:
>
>> TL;DR: Some roadmap ideas. Looks like a lot of work.
>> Comments and improvements welcome:
>> We should replace the Pillar document format
>> by a better one, suitable for WYSIWYG editing and
>> creating long documents.
>
> I agree that Pillar is far from perfect. Do you propose to (1) start
> something from scratch or to (2) improve Pillar? If you propose (1), how
> much do you plan to spend each day and for how long before reaching
> Pillar current's state? If you propose (2), you can start doing
> something small today and finish the same day. With (2) you could
> improve the current situation before we go to bed.

Well, this was a description of where I would like to go
on the map. My first question is, are there enough people who
want to go there too, or am I aiming in the wrong direction?
And if it is a desirable destination, what small experiments
can we do to verify the reachability, and get an idea of how
much work this would be.

Stephan

Stephan Eggermont-3

Re: Improving the documentation model

In reply to this post by Dmitri Zagidulin

On 21/04/15 18:18, Dmitri Zagidulin wrote:
> I strongly believe that the WYSIWYG editing route is a fundamentally
> worse approach for documentation (and textbooks) than text-based
> formatting such as Pillar, Markdown and Asciidoc.

I have a lot of experience using both. The best experience I've had
using Framemaker. Comparing it to Word is a soemwhat similar
experience to explaining non-smalltalkers about image-based development.

> Specifically, it will result in less community contribution, and it will
> make distributed version control of documents much harder.

There is actually no reason why that should be the case, especially
when using semantic markup. I agree that there are lots of WYSIWYG
programs that make it difficult.

> Instead of going the route that you propose (which essentially attempts
> to Word or Google Docs in-image),

My worst experiences with large documents were using Word.
It is designed for small documents, and it took Microsoft 10 years
to make bullet lists work.

> Side-by-side instant preview makes it possible to have the best of both
> worlds, text-based markup and WYSIWYG, without the typical WYSIWYG
> drawbacks (of making distributed version control difficult, first and
> foremost).

I have used side-by-side instant preview since it became available
(Textures on a Macintosh SE/30). Nice for maths, not for large documents.

> 2) Version control, especially with more than one or two collaborators,
> is a *nightmare* with WYSIWYG tools. Look at what the state of the art
> is, at what Microsoft's Word and Google's Docs have been able to
> accomplish, in terms of revision control.

Neither are state of the art. Both are designed for small documents.

> Despite unimaginable amounts of person-hours of development put into it,
> it's pretty much unusable

I fully agree that the collaboration features of Word are unusable.
Word is feature checklist driven.

> We are not Microsoft or Google. We are not going to solve the WYSIWYG
> source control / version control problem better than they are.

> 4) The ability to render source text-based markup into multiple formats
> (PDF, HTML, etc), is *essential*. Going from WYSIWYG to HTML is
> impossible (all attempts to do so, by Microsoft, Adobe, etc, have
> utterly failed).

Repurposing is something Adobe still sells Framemaker for on Windows.
Works perfectly fine. Even has an API.

> Whereas going from text-based to print/PDF is very
> doable (see LaTeX, the entirety of HTML ecosystem, Pillar, etc).
> This is a serious problem that FrameMaker never had to solve.

It is solved by Framemaker. That is an expensive product,
so there are not too many people knowing it.

Stephan