utdrmac
commented
9 years ago +1
Closed aeslaughter closed 9 years ago
utdrmac
commented
9 years ago +1
tbfe-de
commented
9 years ago As you will notice when you search for discussions on the highlighting feature, I once proposed a substantially different approach for highlighting, especially when it comes to partial highlighting inside a line of code, for which back-ticks are used (so no issue for C/C++ but for the use of remark.js with a few Unix/Linux shell script examples, where back-ticks have a syntactical meaning).
Still, at that time I was not able to convince the author that highlighting should be introduced in a less "obstrusive" way or it should at least be possible to switch it off (other that sticking with an older version of remark.js).
To better understand my position you should know that I switched to using remark.js about one-and-a-half years ago and all the documents I give to the participants of the courses I teach (mostly about C/C++) are now based on remark.js.
While I still think highlighting inside code examples is a VERY useful feature for presentations and not only a "nice to have" for those like me who use remark.js in professional teaching, I disliked the way the feature was introduced, especially that it broke valid code by making a leading * that is meant literally "illegal".
And I still feel it is even slightly against the "spirit" of Markdown, to have elements in code block (indented or marked with 3+ back-tick-lines), that are NOT meant literally. My reasoning is not only that this defeats "cut & paste" approaches to insert code snipets, it also would have to be adapted in case of a future feature of remark.js, I'd be happy to see: automatically inserting - and updating(!) - code snippets from compilable (C/C++) examples, so that there are no inadvertant syntax errors (you will always make such when you type code on the keyboard). In the Markdown-converter pandoc there is a nice example with code-blocks that automatically get updated once the file changes in which they are contained (see here: http://pandoc.org/scripting.html#include-files), and I've used similar techniques in the 80s and early 90s when I produced my written documents with nroff/troff under Unix.
Back to remark.js: At that time when the current highlighting feature was implemented and until today I have not enough practice with JavaScript and lack the time to make a different or additional proposal for highlighting, I mean one for which I could show at least a sketchy implementation. But I'm still very interested in discussing better ideas for highlighting code, which also considers the needs and requirements of those of us showing code examples in programming languages that seem to be of secondary interest in the current implementation of the highlighting feauture.
Again, to make it very explicit: this is NO criticism on anybody who actively contributed code to remark.js, let alone its original author! I rate remark.js VERY high among the tools I use, but once an open source project gets a user comunitiy of a certain size there also starts a bit of "obligation" to the users, like it or not. Surely, an open source project will not be immediately killed by not listening to its users, but some (like me) start to slow down updating, continue to use older versions as long as they are just "good enough" (I mostly still use the remark.js version without highlighting) and - may be - might even start their own fork some day. And then, by and by, momentum is taken away from the original branch, and that is another reason why I feel there is an "obligation not to break things" that once worked: It is simply a necessity for open source projects so that brilliant ideas are kept alive for a long time.
Nevertheless a final time: my explicit thanks to Ole Petter Bang for providing us with remark.js, and in case you want to see one of the presentations I've written lately based on remark.js (not on C++ this time but Tcl/Tk), see here: https://github.com/tbfe-de/viva-tcl.
gnab
commented
9 years ago Sorry for the slow response.
I've re-implemented @aeslaughter's pull request and made both line and span highlighting configurable and disabled by default. This will be included in release 0.11.
I understand both of @aeslaughter's and @tbfe-de's issue(s) with the current solution. Hopefully we can get a better way of dealing with this at some point, but now it is at least no longer something that will get in your way with the default configuration.
@tbfe-de: hopefully you may now get up and running on the latest version of remark. I need feedback from people that makes slideshows at the extent that you do.
gnab
commented
9 years ago The wiki is now updated with the two new configuration options for highlighting.
gnab
commented
9 years ago FYI: As of version 0.11, via #220, backticks may now also be escaped with a backslash to prevent highlighting.
gnab
commented
9 years ago Version 0.11 which fixes this has now been released.
aeslaughter
commented
9 years ago Thank you!
tbfe-de
commented
9 years ago Hi Petter,
thanks for your reply and don't worry I might think it were slow.
You encouraged me to switch to the latest release of remark.js and I will probably do so next week, when the C++ course I'm teaching is over.
Also I will be more than happy to give you some feedback on the experience with my "large scale" use of remark.js. Note that all of the following is not urgent. Also I will describe my current use of remark.js before I come to my ideas for improvements.
But first of all, I never regretted (and never was close to regret) my decision to switch from OpenOffice Presents to a markdown-based tool. It was a big win in productivity for me, even though I have some ideas how it could be more perfect for my kind of use.
As you might have noticed if you looked at the Tcl/Tk presentation in my viva-tcl repository, I did a little tweaking with respect to CSS-styling. This all worked well for me from the beginning and I really appreciate the separation of content and styling achievable that way. I was used to that kind of separation since the early days when I prepared my training documents based on Unix nroff/troff.
For the written material of my presentations I've settled to a style that is in the middle between a pure mentioning of some key points (and then talking about them without giving more text to the audience) and a text-book approach that tries to cover everything in a way that it might even just be read (without listening to a speaker) by autodidacts.
Therefore on my presentation pages I typically write prose, but structure the layout of sentences so that it makes the key aspects stand out. I encourage the audience NOT to read too much from the pages while I'm talking, but frequently point with my fingers or a laser pointer to the part of text which is the current subject of my explanations. I do NOT use incrementally displayed lists right now, because I remember (maybe wrongly) I had a problem with printing these pages: in the print-out multiple pages were generated, each one filled with a bit more of content.
This brings me to that: Most of my participants still want print-outs and I find them sometimes turning the pages, e.g. during breaks, apparently looking for something that what was covered in the lesson before or for things to come. That is the main reason I write prose, to give the something to read and recapitulate while I'm NOT talking (in breaks and when the course is over).
With respect to the following I'm personally a bit split in my opinion: I think there is so much information already "out-there" in the Internet and my time is too precious to copy all this, so I tend to just set links for deeper coverage, where possible. And this works best in a purely electronic presentation, which my participants can download and carry with them on an USB stick. But many still want to have it on paper.
I also use footnotes frequently. I do so for advanced aspects that I sometimes cover, sometimes chose to skip (depending on the time left for a topic). Therefore I dim footnote text down via CSS during the presentation so that they do not distract. If during the presentation some aspect needs to get coverage that is already in footnote (maybe there was a question in that direction) I can simply position the mouse pointer over it and it gets highlighted. (In the print-outs footnotes the same as all the other page content, only their font is smaller.)
Currently I do not use speaker notes myself except on the first page where I explain how the participants might use these for their own annotations, if they want to stay with a fully electronic document, INCLUDING their own annotations. About 10% chose this options, the other 90% want the stuff printed.
I know that you implemented speaker notes as response to an issue I once opened, but - at least the first approach - seemed to have hard-wired a number of assumptions with respect to page layout and orientation so that I did not quite achieve the goals I had and stayed with the style described in the above paragraphs.
For print-outs I use an A4 portrait layout with the presentation pages covering the upper half, leaving the lower half of each page for manual annotations. A minor drawback here is that you need a flat binding, so that left and right page could be easily written to (which is difficult to do with a lever arch file style).
Generally I would still appreciate "style-sheet aware speaker notes (I think there is another open issue about it), but I couldn't get it to work (with your initial implementation) for printing (controlled by an @print CSS). Maybe I did something wrong - maybe you improved it the meantime, but for many reasons it is preferable if any layout - also for printing - could be done per style-sheet. Somewhere in the stack of papers that I keep for future reference there is a sketch of the document structure which I reverse-engineered when I tried to come-up with a style-sheet for printing the presentation with speaker notes. It may be useful if YOU documented the DOM-structure "officially" somewhere. To me (i.e. from what I reverse-engieneered), the DOM looks a bit "grown with time", not "designed for a purpose", but this is not meant as criticism and you may have had good reasons to nest the document elements in the way they are now nested.
Finally for some things that were nice to have in remark.js - even nicer if they are already there and I didn't notice (I've not scanned all the opened and closed issues whether the below is among them. So, if one of the following is already implemented, I'd be pleased to learn it.)
I put the following list approximately in my order of preference, most wanted first:
The result (ideally) were a single html file which I can give to the participants. Especially it should resolve and automatically include the definitions of all the page-templates used in that particular book. Just as an idea: Maybe remark.js could scan a directory which contains files with page templates and automatically pull-in what is used on a per-name base (name of the template-page, NOT the file in which is held).
This could nicely solve another task I need to do manually in the moment, which is branding the presentations depending on the customer (typically the customers name appears in the page footer, and may be a customer specific logo too). Currently I change the branding by hand in the template pages, but if remark.js would pull-in the required template-pages automatically from a directory I name, I could simply hold several pre-branded template-page versions (and style sheets) in customer-specific sub-directories and name the appropriate one when I generate the presentation.
Thinking (and writing) about it feel what I described in the last sections need NOT be part of remark.js but could be achieved with some (JavaScript / node.js) tool outside of it. I think such a tool could add value to remark.js and I also think that what I described is not achievable with a more generic approach, as the template page mechanism is a special feature of remarks.js - but a very useful one!
But IF such a feature gets considered, it needs also be prepared for the fact that compilable examples in C++ typically a bit or even much too large to fit on a single slide. Therefore scrollable and editable text-areas were preferable. When edited, the content need NOT be stored back somewhere (but it should eventually be sent to the compile service in its modified form). The icing on the cake were, if for printing and when displaying a page for the first time, such a "C++ example text box" could be scrolled to a preferred viewport, one that puts focus to what is covered on the presentation page.
So far some thoughts about possible future extensions and again thanks for creating remark.js: it "felt" right when I saw and tried it the first time (I considered several HTML slide-show alternatives two years ago), and it still feels right today and I will try to upgrade to the most recent version soon.
Best Regards, Martin
On 21.06.2015 19:27, Ole Petter Bang wrote:
Sorry for the slow response.
I've re-implemented @aeslaughter https://github.com/aeslaughter's pull request and made both line and span highlighting configurable and disabled by default. This will be included in release 0.11.
I understand both of @aeslaughter https://github.com/aeslaughter's and @tbfe-de https://github.com/tbfe-de's issue(s) with the current solution. Hopefully we can get a better way of dealing with this at some point, but now it is at least no longer something that will get in your way with the default configuration.
@tbfe-de https://github.com/tbfe-de: hopefully you may now get up and running on the latest version of remark. I need feedback from people that makes slideshows at the extent that you do.
— Reply to this email directly or view it on GitHub https://github.com/gnab/remark/issues/192#issuecomment-113933279.
aeslaughter
commented
9 years ago Petter,
You may also be interested to know that we are using Remark.js to deliver a two-day training for our framework training (www.mooseframework.org). We are actually extracting content from our wiki (www.mooseframework.org/wiki) and creating Remark.js slides automatically.
Thanks for the great product.
Andrew
On Mon, Jun 22, 2015 at 2:59 PM, Martin Weitzel notifications@github.com wrote:
Hi Petter,
thanks for your reply and don't worry I might think it were slow.
You encouraged me to switch to the latest release of remark.js and I will probably do so next week, when the C++ course I'm teaching is over.
Also I will be more than happy to give you some feedback on the experience with my "large scale" use of remark.js. Note that all of the following is not urgent. Also I will describe my current use of remark.js before I come to my ideas for improvements.
But first of all, I never regretted (and never was close to regret) my decision to switch from OpenOffice Presents to a markdown-based tool. It was a big win in productivity for me, even though I have some ideas how it could be more perfect for my kind of use.
As you might have noticed if you looked at the Tcl/Tk presentation in my viva-tcl repository, I did a little tweaking with respect to CSS-styling. This all worked well for me from the beginning and I really appreciate the separation of content and styling achievable that way. I was used to that kind of separation since the early days when I prepared my training documents based on Unix nroff/troff.
For the written material of my presentations I've settled to a style that is in the middle between a pure mentioning of some key points (and then talking about them without giving more text to the audience) and a text-book approach that tries to cover everything in a way that it might even just be read (without listening to a speaker) by autodidacts.
Therefore on my presentation pages I typically write prose, but structure the layout of sentences so that it makes the key aspects stand out. I encourage the audience NOT to read too much from the pages while I'm talking, but frequently point with my fingers or a laser pointer to the part of text which is the current subject of my explanations. I do NOT use incrementally displayed lists right now, because I remember (maybe wrongly) I had a problem with printing these pages: in the print-out multiple pages were generated, each one filled with a bit more of content.
This brings me to that: Most of my participants still want print-outs and I find them sometimes turning the pages, e.g. during breaks, apparently looking for something that what was covered in the lesson before or for things to come. That is the main reason I write prose, to give the something to read and recapitulate while I'm NOT talking (in breaks and when the course is over).
With respect to the following I'm personally a bit split in my opinion: I think there is so much information already "out-there" in the Internet and my time is too precious to copy all this, so I tend to just set links for deeper coverage, where possible. And this works best in a purely electronic presentation, which my participants can download and carry with them on an USB stick. But many still want to have it on paper.
I also use footnotes frequently. I do so for advanced aspects that I sometimes cover, sometimes chose to skip (depending on the time left for a topic). Therefore I dim footnote text down via CSS during the presentation so that they do not distract. If during the presentation some aspect needs to get coverage that is already in footnote (maybe there was a question in that direction) I can simply position the mouse pointer over it and it gets highlighted. (In the print-outs footnotes the same as all the other page content, only their font is smaller.)
Currently I do not use speaker notes myself except on the first page where I explain how the participants might use these for their own annotations, if they want to stay with a fully electronic document, INCLUDING their own annotations. About 10% chose this options, the other 90% want the stuff printed.
I know that you implemented speaker notes as response to an issue I once opened, but - at least the first approach - seemed to have hard-wired a number of assumptions with respect to page layout and orientation so that I did not quite achieve the goals I had and stayed with the style described in the above paragraphs.
For print-outs I use an A4 portrait layout with the presentation pages covering the upper half, leaving the lower half of each page for manual annotations. A minor drawback here is that you need a flat binding, so that left and right page could be easily written to (which is difficult to do with a lever arch file style).
Generally I would still appreciate "style-sheet aware speaker notes (I think there is another open issue about it), but I couldn't get it to work (with your initial implementation) for printing (controlled by an @print CSS). Maybe I did something wrong - maybe you improved it the meantime, but for many reasons it is preferable if any layout - also for printing - could be done per style-sheet. Somewhere in the stack of papers that I keep for future reference there is a sketch of the document structure which I reverse-engineered when I tried to come-up with a style-sheet for printing the presentation with speaker notes. It may be useful if YOU documented the DOM-structure "officially" somewhere. To me (i.e. from what I reverse-engieneered), the DOM looks a bit "grown with time", not "designed for a purpose", but this is not meant as criticism and you may have had good reasons to nest the document elements in the way they are now nested.
Finally for some things that were nice to have in remark.js - even nicer if they are already there and I didn't notice (I've not scanned all the opened and closed issues whether the below is among them. So, if one of the following is already implemented, I'd be pleased to learn it.)
I put the following list approximately in my order of preference, most wanted first:
- There should be a way to create a TOC, as well for a whole presentation but also for subsection. Currently I do this manually which is time consuming and error prone. I think it should either work based on header levels (h1, h2, h3 ... elements) or on special page attributes (but in the latter case there should be an option to turn these into headers). I know enough of JavaScript to understand that it is easy to traverse the document structure, so I think the TOC is not too hard to do. The more serious decisions may be how to turn the TOC into a page, what to do if one page cannot hold it all, and how to define that only some subsection (and which one) should go into the TOC.
- There should be some way to turn a "multi-file" presentation into a "single html file". (I think I've seen an open issue for it.) Of course I understand that I can copy all the necessary ingredients into a single html file manually (e.g. the minified remark.js and the style sheet), but what I have in mind goes a bit further:
- I would like to structure my course documents into major chapters and just "pull-in" what is necessary for a specific course by listing its chapters. Ideally this would work "dependency based" (a bit similar to a Makefile), i.e. what is "pullled in as content" may be a remark.js presentation of a chapter or another description how in turn to construct the chapter from smaller parts.
The result (ideally) were a single html file which I can give to the participants. Especially it should resolve and automatically include the definitions of all the page-templates used in that particular book. Just as an idea: Maybe remark.js could scan a directory which contains files with page templates and automatically pull-in what is used on a per-name base (name of the template-page, NOT the file in which is held).
This could nicely solve another task I need to do manually in the moment, which is branding the presentations depending on the customer (typically the customers name appears in the page footer, and may be a customer specific logo too). Currently I change the branding by hand in the template pages, but if remark.js would pull-in the required template-pages automatically from a directory I name, I could simply hold several pre-branded template-page versions (and style sheets) in customer-specific sub-directories and name the appropriate one when I generate the presentation.
Thinking (and writing) about it feel what I described in the last sections need NOT be part of remark.js but could be achieved with some (JavaScript / node.js) tool outside of it. I think such a tool could add value to remark.js and I also think that what I described is not achievable with a more generic approach, as the template page mechanism is a special feature of remarks.js - but a very useful one!
- For my specific use only it were extremely nice to include (complete) C++ code examples in a remark.js presentation in a way that these units of source code be forwarded to some online compilation tool. You may or may not know http://cppereference.com and http://cplusplus.com (to which I link a lot from my presentations for reference documentation). Both sites now hold all their examples in a form that can be handed to coliru (cppreference.com) or cpp.sh (cplusplus.com).
But IF such a feature gets considered, it needs also be prepared for the fact that compilable examples in C++ typically a bit or even much too large to fit on a single slide. Therefore scrollable and editable text-areas were preferable. When edited, the content need NOT be stored back somewhere (but it should eventually be sent to the compile service in its modified form). The icing on the cake were, if for printing and when displaying a page for the first time, such a "C++ example text box" could be scrolled to a preferred viewport, one that puts focus to what is covered on the presentation page.
So far some thoughts about possible future extensions and again thanks for creating remark.js: it "felt" right when I saw and tried it the first time (I considered several HTML slide-show alternatives two years ago), and it still feels right today and I will try to upgrade to the most recent version soon.
Best Regards, Martin
On 21.06.2015 19:27, Ole Petter Bang wrote:
Sorry for the slow response.
I've re-implemented @aeslaughter https://github.com/aeslaughter's pull request and made both line and span highlighting configurable and disabled by default. This will be included in release 0.11.
I understand both of @aeslaughter https://github.com/aeslaughter's and @tbfe-de https://github.com/tbfe-de's issue(s) with the current solution. Hopefully we can get a better way of dealing with this at some point, but now it is at least no longer something that will get in your way with the default configuration.
@tbfe-de https://github.com/tbfe-de: hopefully you may now get up and running on the latest version of remark. I need feedback from people that makes slideshows at the extent that you do.
— Reply to this email directly or view it on GitHub https://github.com/gnab/remark/issues/192#issuecomment-113933279.
— Reply to this email directly or view it on GitHub https://github.com/gnab/remark/issues/192#issuecomment-114260698.
tbfe-de
commented
9 years ago Hi Petter,
I switched to the latest version today and highlighting in code examples looks really nice and would be a useful feature for me.
Nevertheless I had to back-up to the older version I used so far as in the new version the out-of-line hyperlinks do not work any more.
I really use these a lot as (IMHO) they make Markdown more readable, so having to make a trade-off, I preferred the out-of-line links over highlighting.
(Might it be I am the only one who uses MD with out-of-line links ...?)
Best Regards, Martin
On 06/21/2015 07:27 PM, Ole Petter Bang wrote:
Sorry for the slow response.
I've re-implemented @aeslaughter https://github.com/aeslaughter's pull request and made both line and span highlighting configurable and disabled by default. This will be included in release 0.11.
I understand both of @aeslaughter https://github.com/aeslaughter's and @tbfe-de https://github.com/tbfe-de's issue(s) with the current solution. Hopefully we can get a better way of dealing with this at some point, but now it is at least no longer something that will get in your way with the default configuration.
@tbfe-de https://github.com/tbfe-de: hopefully you may now get up and running on the latest version of remark. I need feedback from people that makes slideshows at the extent that you do.
— Reply to this email directly or view it on GitHub https://github.com/gnab/remark/issues/192#issuecomment-113933279.
This is bad when showing C++, which can certainly have valid lines that start with *