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
stephan <stephan@stack.nl> 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
On 21/04/15 17:59, Damien Cassou wrote:
stephan <stephan@stack.nl> 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 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 -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4820935.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <sean@clipperadams.com> 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.)
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 <dmitri@zagidulin.net> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <sean@clipperadams.com> 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.)
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] < ml-node+s1294792n4820973h56@n4.nabble.com> 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] <http:///user/SendEmail.jtp?type=node&node=4820973&i=0>> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email] <http:///user/SendEmail.jtp?type=node&node=4820973&i=1>> 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.ht... To start a new topic under Pharo Smalltalk Developers, email ml-node+s1294792n1294837h40@n4.nabble.com To unsubscribe from Pharo Smalltalk Developers, click here <http://forum.world.st/template/NamlServlet.jtp?macro=unsubscribe_by_code&nod...> . NAML <http://forum.world.st/template/NamlServlet.jtp?macro=macro_viewer&id=instant...>
----- Nacho Smalltalker apprentice. Buenos Aires, Argentina. -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4820976.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
nacho <0800nacho@gmail.com> writes:
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.
in the following thread, I reference a prototype that does just that: http://forum.world.st/Class-comments-rendered-in-Nautilus-through-Pillar-td4... -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill
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" <kilon.alios@gmail.com> 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 <dmitri@zagidulin.net> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <sean@clipperadams.com
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 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.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
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 <sean@clipperadams.com> 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.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Le 21/4/15 21:25, phil@highoctane.be a écrit :
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.
should be a visitor :)
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" <kilon.alios@gmail.com <mailto:kilon.alios@gmail.com>> 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 <dmitri@zagidulin.net <mailto:dmitri@zagidulin.net>> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <sean@clipperadams.com <mailto:sean@clipperadams.com>> 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.)
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 <dmitri@zagidulin.net <mailto:dmitri@zagidulin.net>> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <sean@clipperadams.com <mailto:sean@clipperadams.com>> 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.)
On Tue, Apr 21, 2015 at 8:48 PM, Nicolas Anquetil <nicolas.anquetil@inria.fr
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 <dmitri@zagidulin.net> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris < sean@clipperadams.com> 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.)
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 <nicolas.anquetil@inria.fr
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 <dmitri@zagidulin.net> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris < sean@clipperadams.com> 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.)
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] < ml-node+s1294792n4820989h52@n4.nabble.com> 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] <http:///user/SendEmail.jtp?type=node&node=4820989&i=0>> 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] <http:///user/SendEmail.jtp?type=node&node=4820989&i=1>> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris <[hidden email] <http:///user/SendEmail.jtp?type=node&node=4820989&i=2>> 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.ht... To start a new topic under Pharo Smalltalk Developers, email ml-node+s1294792n1294837h40@n4.nabble.com To unsubscribe from Pharo Smalltalk Developers, click here <http://forum.world.st/template/NamlServlet.jtp?macro=unsubscribe_by_code&nod...> . NAML <http://forum.world.st/template/NamlServlet.jtp?macro=macro_viewer&id=instant...>
----- Nacho Smalltalker apprentice. Buenos Aires, Argentina. -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4820991.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
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 <kilon.alios@gmail.com> 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 < nicolas.anquetil@inria.fr> 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 <dmitri@zagidulin.net> wrote:
On Tue, Apr 21, 2015 at 12:15 PM, Sean P. DeNigris < sean@clipperadams.com> 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.)
"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.
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 -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4821001.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
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.
I do not care about pillar. I care about we have it, it is working and improving and we can control it. I care that soon we can have a good solution and do something else. I do not have 10 years for the perfect solution but if you come with it, maintain it, enhance and I can extend it in case you disappear then I buy it. Stef
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-2f368bd0a2... 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 <stephan@stack.nl> 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 [image: 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
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
Dmitri Zagidulin <dmitri@zagidulin.net> writes:
* 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).
could you please add missing features to http://www.smalltalkhub.com/#!/~Pier/Pillar
* Invest in instant-preview tech, in-image.
we have this prototype already: http://forum.world.st/Class-comments-rendered-in-Nautilus-through-Pillar-td4... But its author waits for TxText and Athens before investing more of his time.
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).
what I don't like about WYSIWYG word processors is that they hide the content. I want to control my content. I want to immediately see if a line is a section title (semantically) or if it's just bold and huge. I want to immediately see if a section title is automatically numbered or if the number was written manually.
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).
Luc improved the pillar plugin for TextMate so that it has instant preview too.
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).
I agree that this is a very important point.
- Asciidoc has the ability to do file imports (compose a larger document out of smaller docs)
Cyril implemented that in Pillar last week.
* 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.
Cyril has to revise that part.
* 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.
this is on Pillar roadmap as well: http://www.smalltalkhub.com/#!/~Pier/Pillar -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill
Damien Cassou-2 wrote
what I don't like about WYSIWYG word processors is that they hide the content. I want to control my content. I want to immediately see if a line is a section title (semantically) or if it's just bold and huge. I want to immediately see if a section title is automatically numbered or if the number was written manually. ...
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). I agree that this is a very important point.
These are very valid critiques of current non-OOP, pink plane approaches, but in fact there is no inherent conflict between WYSIWYG and e.g. Pillar. If we start from our intentions, either from the list I started or your own, it's easy to see how to have it all. Yes, in a rich text editor, one doesn't know if it's just "bold and big" or a section title. But we are not talking about jerry rigging a generic editor such as Word to do something for which it was never intended. We could, as a start, and an easy bridge between the two POVs, create a Pillar WYSIWYG editor, where the only options are semantic. So the menu choice/button/whatever would be all domain related, so when you saw "big and bold", you would be confident that it was just a visual cue for a section title, which is important because visual thinking is an important process - and separate from the intellectual processing of syntax. Making a richer interface does not have to mean giving anything up. ----- Cheers, Sean -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4821107.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Sean P. DeNigris <sean@clipperadams.com> writes:
Damien Cassou-2 wrote
what I don't like about WYSIWYG word processors is that they hide the content. I want to control my content. I want to immediately see if a line is a section title (semantically) or if it's just bold and huge. I want to immediately see if a section title is automatically numbered or if the number was written manually. ...
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). I agree that this is a very important point.
These are very valid critiques of current non-OOP, pink plane approaches, but in fact there is no inherent conflict between WYSIWYG and e.g. Pillar. If we start from our intentions, either from the list I started or your own, it's easy to see how to have it all. Yes, in a rich text editor, one doesn't know if it's just "bold and big" or a section title. But we are not talking about jerry rigging a generic editor such as Word to do something for which it was never intended. We could, as a start, and an easy bridge between the two POVs, create a Pillar WYSIWYG editor, where the only options are semantic. So the menu choice/button/whatever would be all domain related, so when you saw "big and bold", you would be confident that it was just a visual cue for a section title, which is important because visual thinking is an important process - and separate from the intellectual processing of syntax. Making a richer interface does not have to mean giving anything up.
ok for me. -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill
To me this whole notion of which format to use, if it should be WYSIWYG, and what kind of markup to use is somewhat dependent on that usage scenarios one consider. I too would like to see something which moves beyond plain strings. As the computer scientist I am, would also like it to be something uniform across usage. However - there is difference in how we I view a comment and how I view a book. In a method comment I would like to be able to add a little bold, and perhaps a few links to elsewhere. In a class method I would like to be to also do lists, perhaps a heading or two (which I could do with bold perhaps). A package comment I start to want to include diagrams and images. In a full book or paper, well, I want it all there (aka level of Latex or Word). Pillar is no worse than 99% of the other markup's out there, so fine with me. What I tried in my little Pillar/Nautilus combo was to show how one can make a morph which shows pillar markup as a rendered text (as opposed to string), but editing that text is done by editing the pillar markup. I believe someone with more experience than I can make one that works more smoothly. Also, I believe the same trick can be used of inlined method comments. So, my point is, that Pillar and other markup languages were intended to be for wiki, and web pages, not for books. That is something at the level of class comments or package comments. -- View this message in context: http://forum.world.st/Improving-the-documentation-model-tp4820814p4821286.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Am 21.04.2015 15:11 schrieb "stephan" <stephan@stack.nl>:
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.
---
Nice idea, but
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.
Let us focus on this and make it work. TxText is not ready yet. Athens font rendering still has some issues. (And even with the good old TextMorph, we can not even draw underlined Text or sub/superscript)
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.
Let us focus on this and make it work. TxText is not ready yet. Athens font rendering still has some issues. (And even with the good old TextMorph, we can not even draw underlined Text or sub/superscript)
+1
Le 21/04/2015 15:11, stephan a écrit :
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.
People mentioned Lyx[1] and there is TeXmacs[2] as well. [1] https://en.wikipedia.org/wiki/LyX [2] https://en.wikipedia.org/wiki/GNU_TeXmacs -- Dr. Geo - http://drgeo.eu iStoa - http://istoa.drgeo.eu
participants (13)
-
Damien Cassou -
Dmitri Zagidulin -
Hilaire -
Kasper Osterbye -
kilon alios -
nacho -
Nicolai Hess -
Nicolas Anquetil -
phil＠highoctane.be -
Sean P. DeNigris -
stephan -
Stephan Eggermont
-
stepharo