Hi Sönke, I have recently noticed, that it's even simpler to add extensions to asciidoctor. I did nothing other than that with my static jar (did that cause I couldn't release the artifact myself and that was the easy way out)
However I still have to find out how to do that in practice. In general you can provide your own macros that handle generation of blocks, I've seen it before and just have to find it again. We could whip up a set of macros that we agreed upon and release that and use those in our presentations. Also can you always embed custom HTML by wrapping that in "++++" blocks ... I'm using that in my latest talk slides to use other chart libraries. And regarding charts, eating your own dogfood etc. ... writing an extension for Apache ECharts [1] could be a good option. Chris [1] http://echarts.apache.org/ Am 04.03.19, 12:48 schrieb "Sönke Liebau" <soenke.lie...@opencore.com.INVALID>: Heyho, I'll try to take a step backwards to look at the large picture here for a second. In general I really love what you have done Chris! Having everything in an asciidoc file is great and building with Maven, I think most people can get behind that (certainly more than for any other solution :) ). Before talking about specific implementations for charts, graphs, etc. I think we should maybe try and discuss the overall design of what we will be trying to build and how we want to organize it. As I said, I'd be on board with Maven and Asciidoctor as vehicles. Reveal.js I'll need to look at further, but the target format is probably a less final decision than the format that we maintain our content in anyway. For graphs etc. I personally think that the target should be some sort of plugin system (Asciidoctor already has one, maybe we don't need anything beyond that) that we can use to slowly grow a curated list of acceptable formats to create content in. For diagrams there is a huge list of services that we could look at out there: cacoo, draw.io, dia, yEd, gliffy, LucidChart, ... We should probably come up with a more or less formalized way of accepting new formats to avoid needlessly growing the list, but I also see no need to be too restrictive here. Best regards, Sönke On Fri, Mar 1, 2019 at 7:59 PM Lars Francke <lars.fran...@gmail.com> wrote: > > Thank you for sharing Christofer. I need a quiet minute to look at that. > > What I like is that it builds easily using Maven, content in Asciidoc, > easily versionable etc., the speaker notes are good > I see that reveal.js also does PDF export. > > The only thing I don't immediately like are the diagram options. I think > they are pretty...ugly. > > I used the same example[1] to play around a bit and newer versions work as > well. > > One thing I haven't tried yet is how to "depend" on other content. If we > have a ZooKeeper Training which we'd like to include in a Hadoop ecosystem > training for example. And would all our content be in Maven projects? > > I believe it'd be great if we could have "content-only" projects and then > other projects that do the packaging/converting/distributing part. > > Cheers, > Lars > > [1] < > https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoc-to-revealjs-example > > > > On Mon, Feb 25, 2019 at 7:53 PM Dmitriy Pavlov <dpav...@apache.org> wrote: > > > Yes, for me it works. Thank you > > > > пн, 25 февр. 2019 г., 20:54 Christofer Dutz <christofer.d...@c-ware.de>: > > > > > Does it work now? > > > Even if I said "everyone with a link" slak keeps on asking me to grant > > > permissions :/ > > > > > > Chris > > > > > > > > > > > > Am 25.02.19, 18:47 schrieb "Dmitriy Pavlov" <dpav...@apache.org>: > > > > > > Hi Chris, could you please add view permission for the google > > document? > > > Thank you. > > > > > > пн, 25 февр. 2019 г. в 20:44, Christofer Dutz < > > > christofer.d...@c-ware.de>: > > > > > > > Hi all, > > > > > > > > I'm not suggesting to build something ... it's sort of already > > there: > > > > Here an export of one of my current presentation template: > > > > > > > > https://drive.google.com/open?id=1pZ5l9X__gTM4vg2PJRbc-0GXuEf058aI > > > > > > > > It uses Asciidoc and I quite like that in general for all sorts of > > > use > > > > cases. > > > > Markdown to me appears a lot less powerful and extensible (but that > > > just > > > > might be me dropping the ball on that quite some time ago) > > > > Doc-book and Latech I remember being quite low level and I don't > > know > > > > reStructuredText. > > > > > > > > Regarding images I started adopting PlantUML and DITAA quite some > > > time ago > > > > and quite recently am updating to SVGBob > > > > https://github.com/ivanceras/svgbob > > > > > > > > Regarding your format ... just have a look at the content of > > > > src/main/asciidoc/index.adoc > > > > In the Zip file ... that's pretty much what you describe. > > > > Most of these require some installed open-source tools to render > > > images > > > > correctly and I have started setting up some init scripts to > > install > > > > missing things, but that still needs quite a lot of love to be in a > > > > releasable state. > > > > Currently it's just something I use myself and the scripts are > > more a > > > > reminder to myself of how to install things. > > > > > > > > Please have a look. > > > > > > > > Chris > > > > > > > > > > > > Am 25.02.19, 17:42 schrieb "Sönke Liebau" < > > > soenke.lie...@opencore.com > > > > .INVALID>: > > > > > > > > I agree with Mirko, I don't think we should head down the route > > > of > > > > creating a full blown publishing framework or similar. > > > > > > > > The issue, at least to my mind, is divided into two main > > things: > > > > - text content (which I consider to include tables, lists, > > etc.) > > > > - graphical content > > > > > > > > For text content there are quite a few good options out there, > > we > > > > probably just need to conduct a hunt for the main competitors > > and > > > > agree on one that meets most needs. Otoh the main ones are > > > probably: > > > > - asciidoc > > > > - markdown > > > > - doc-book > > > > - latex > > > > - reStructuredText > > > > > > > > For graphical content my personal opinion is that the > > > possibilities > > > > are simply endless and we should not necessarily be trying to > > > restrict > > > > what people may want to use either. For the "compiled" > > > presentation in > > > > the end I think the common denominator will always be "a > > > picture" (no > > > > other way to express a photo or a logo) and I personally think > > > it is > > > > fine. > > > > The way of getting at this image is what I think we should be > > > focusing > > > > on, so the basic idea would be to have a text representation of > > > the > > > > image in version control and at "compile" time create the > > actual > > > image > > > > that is then part of the release. > > > > For the "text representation" part there are a lot of possible > > > > options, what I have used a lot in the past is for example: > > > > - websequencediagrams [1] > > > > - draw.io [2] > > > > > > > > But since there are so many services out there that offer > > > something > > > > similar I think this should really be something extensible so > > > that > > > > people can develop converters for their own formats. For the > > > Apache > > > > training content we should then probably have a rule that only > > > > converters that are part of the official repo may be used for > > > content, > > > > which allows us to curate a little. > > > > > > > > So basically in version control slides might then look like > > this: > > > > > > > > == Slide One > > > > > > > > * Foo > > > > * Bar > > > > * World > > > > > > > > == Slide Two > > > > >>> imageContent(websequencediagram) > > > > User->Server: Connect > > > > Server->User: Respond > > > > <<< > > > > > > > > Whereas the content of the wsd part would be replaced by the > > > > corresponding picture when building the actual slides. > > > > > > > > > > > > Hope that made a little sense? Otherwise I am happy to > > elaborate > > > > further :) > > > > > > > > Best regards, > > > > Sönke > > > > > > > > > > > > [1] https://www.websequencediagrams.com/ > > > > [2] https://www.draw.io/ > > > > > > > > On Mon, Feb 25, 2019 at 5:17 PM Mirko Kämpf < > > > mirko.kae...@gmail.com> > > > > wrote: > > > > > > > > > > Hi, > > > > > regarding content versioning, I suggest to search formar like > > > > doc-book xml > > > > > (it can be anything which allows Separation of content and > > > Style). > > > > > With this, we can generate PDF, PPT, Google-Presentations for > > > final > > > > > customization. > > > > > > > > > > The issue is, how to convert a result from a creativity > > session > > > > incl. media > > > > > content / sketches / fotos back into such a fundamental > > format. > > > > > > > > > > I suggest not to try to build another CMS or publishing > > > Framework, > > > > but > > > > > rather Focus on the process of content creation/Update. > > > > > > > > > > Cheers, > > > > > Mirko > > > > > > > > > > Lars Francke <lars.fran...@gmail.com> schrieb am Sa., 23. > > Feb. > > > > 2019, 16:23: > > > > > > > > > > > On Sat, Feb 23, 2019 at 7:31 PM Sharan Foga < > > > sha...@apache.org> > > > > wrote: > > > > > > > > > > > > > > > > > > > > > > > > > > > On 2019/02/22 23:12:29, Lars Francke < > > > lars.fran...@gmail.com> > > > > wrote: > > > > > > > > During the DISCUSS and VOTE threads I tried to postpone > > > any > > > > discussion > > > > > > > > about the actual content and technical bits but now > > > would be a > > > > great > > > > > > time > > > > > > > > to start. > > > > > > > > > > > > > > > > I know that Dmitriy was eager to get started and > > > Christofer > > > > also > > > > > > > explained > > > > > > > > his workflow briefly. Maybe you could go into more > > > detail? > > > > > > > > Christofer demonstrated his own tooling to us and I > > > really > > > > liked it. > > > > > > This > > > > > > > > could be a great start. > > > > > > > > > > > > > > > > I'm sorry this is going to be a bit longer and maybe a > > > bit > > > > "rambling". > > > > > > > Take > > > > > > > > it as you will. I just needed to write it down once :) > > > > > > > > > > > > > > > > When we've done trainings so far they usually consist > > of > > > a > > > > couple of > > > > > > > things: > > > > > > > > > > > > > > > > * Slides (for us usually in Powerpoint) > > > > > > > > * Whiteboard sessions (usually the most interesting > > parts > > > > because they > > > > > > > > usually are the result of attendee feedback/questions) > > > > > > > > * Labs (the actual content, things that attendees need > > to > > > > "solve"/do) > > > > > > > > * Lab setup (especially for the larger distributed > > > systems > > > > getting a > > > > > > > > realistic setup of the tools itself for all attendees > > > isn't > > > > trivia > > > > > > > > > > > > > > > > I'm sure I'm missing something. > > > > > > > > > > > > > > Thanks Lars - this is good. Off the top of my head a > > > couple of > > > > things > > > > > > came > > > > > > > to mind - the first is testing (to see how much attendees > > > have > > > > learned > > > > > > and > > > > > > > this could be linked to certification which I think was > > > > mentioned in one > > > > > > of > > > > > > > the threads) and the second was a way of collecting > > > feedback > > > > about the > > > > > > > training - so perhaps a survey > > > > > > > > > > > > > > > > > > > Those are good points I didn't think of. > > > > > > > > > > > > Tests we have never done by choice but I see that people > > > might be > > > > > > interested in them and surveys are something that we > > probably > > > > should have > > > > > > done ourselves a long time ago already. So: Definitely. > > > > > > > > > > > > > > > > > > > > What should our scope be? > > > > > > > > Our initial idea centered around Slides and Labs. It > > > would be > > > > great to > > > > > > > also > > > > > > > > have something that makes the Labs setup easier but in > > > our > > > > experience > > > > > > > > that's pretty hard (e.g. corporate firewalls don't > > allow > > > > access to X or > > > > > > > Y) > > > > > > > > to make generic (that shouldn't stop us from trying!) > > > > > > > > > > > > > > > > Slides: > > > > > > > > I'd love to have a workflow where I can design slides > > > > entirelly in > > > > > > > > Asciidoc. That makes them easily versionable and > > > composable. > > > > Should we > > > > > > > > allow multiple formats? If we decide on a text-only > > > format and > > > > someone > > > > > > > > donates a bunch of courses in Powerpoint. Would we deny > > > that? > > > > > > > > > > > > > > I think that we would want to accept contribution that is > > > > relevant. There > > > > > > > may be an overhead to convert the content into a more > > > generic > > > > format but > > > > > > > that's doable especially if it encourages contributions. > > > > > > > > > > > > > > > > > > > I assume you meant "any contribution"? > > > > > > In general I agree but any binary format (e.g. Powerpoint - > > > I'll > > > > call it > > > > > > binary even though it's really XML now but it's pretty > > > useless for > > > > what I'm > > > > > > going to mention or PDF) has the problem that doing reviews > > > is > > > > tedious to > > > > > > impossible. There's no good way (I know of) to create diffs > > > for > > > > example and > > > > > > people on Linux are left out entirely for Powerpoint. > > > > > > > > > > > > I currently believe having "one true format" for all of > > them > > > is a > > > > good idea > > > > > > (I am happy to be convinced otherwise), maybe with a kind > > of > > > > "staging" area > > > > > > of accepted contributons that have yet to be converted and > > > are not > > > > coverd > > > > > > by "quality guarantees". > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > Labs: > > > > > > > > Similarly for Labs we've had a good experience with > > > (e.g.) > > > > > > > > https://antora.org/ which also allows to create > > > documentation > > > > in > > > > > > > Asciidoc > > > > > > > > and create a website out of it. But there's lots of > > > ideas on > > > > how to > > > > > > > improve > > > > > > > > this (e.g. Notebooks in Zeppelin) and it'll also be way > > > > different > > > > > > > depending > > > > > > > > on the training topic. > > > > > > > > > > > > > > > > Audience/Customizability/Composability > > > > > > > > I would assume that our trainings will also be used by > > > > non-commercial > > > > > > > folks > > > > > > > > or people needing to give a training in-house at their > > > > companies. For > > > > > > > them > > > > > > > > a prepared "deck" with ASF branding is fine but others > > > might > > > > want to > > > > > > > > incorporate these slides into their own work (see the > > > Legal > > > > thread) and > > > > > > > > also compose their own out of smaller "components". > > > > > > > > So for me a good thing would be if we produce smaller > > > > "chapters" of > > > > > > > things > > > > > > > > that can then be composed however one would like and to > > > make > > > > our > > > > > > product > > > > > > > > customizabile (e.g. custom header, footer, background > > > colors > > > > etc.) > > > > > > > > > > > > > > > > Apache vs. non-Apache // Product vs. non-product > > > > > > > > I wouldn't want to limit us to Apache products. I don't > > > see a > > > > reason > > > > > > not > > > > > > > to > > > > > > > > also talk about 3rd party tools. Especially if they are > > > tightly > > > > > > > integrated > > > > > > > > into the ecosystem (e.g. the ELK stack is often used > > > alongside > > > > Hadoop). > > > > > > > > > > > > > > +1 I like the idea and it also could make our content > > > valuable > > > > to others > > > > > > > outside the ASF > > > > > > > > > > > > > > > > > > > > > > > I also don't see a reason to only focus on > > > > < > > > > > https://maps.google.com/?q=%3E+I+also+don't+see+a+reason+to+only+focus+on+&entry=gmail&source=g > > > >single > > > > products. A training > > > > > > > > could focus on "IoT" and cover lots of products. > > > > > > > > > > > > > > +1 this will also give the Apache projects visibility of > > > others > > > > in the > > > > > > > same domain. I'm not really sure how cross pollinated our > > > > projects are. > > > > > > > > > > > > > > > > > > > > > > > In a similar vein it doesn't always have to be > > technical > > > > products. I've > > > > > > > > already been approached from multiple people about "The > > > Apache > > > > Way" > > > > > > > > presentations. Now whether they make more sense in > > > ComDev is > > > > to be > > > > > > > decided. > > > > > > > > Maybe Sharan can weigh in? > > > > > > > > > > > > > > I think Training would be a great place for managing the > > > Apache > > > > Way > > > > > > > content. In ComDev we've tried to gather and collate this > > > type > > > > of content > > > > > > > and have ended up with a page of different presentation > > > slides. > > > > Each > > > > > > person > > > > > > > has a different spin on it - so creating something > > > standard as a > > > > nice off > > > > > > > the shelf template that anyone can use will be great. And > > > I'm > > > > happy to > > > > > > > ensure we maintain a link and communicate with ComDev > > > regularly > > > > so > > > > > > > potential contributors know about what we are doing here > > in > > > > Training. > > > > > > > > > > > > > > > > > > > Okay, that's good! > > > > > > As you said: There's a dozen of those out there now. > > > > > > > > > > > > Lars > > > > > > > > > > > > > > > > > > > Thanks > > > > > > > Sharan > > > > > > > > > > > > > > > > > > > > > > > Thanks, > > > > > > > > Lars > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > Sönke Liebau > > > > Partner > > > > Tel. +49 179 7940878 <+49%20179%207940878> > > > > OpenCore GmbH & Co. KG - Thomas-Mann-Straße 8 - 22880 Wedel - > > > Germany > > > > > > > > > > > > > > > > > > > > > > > -- Sönke Liebau Partner Tel. +49 179 7940878 OpenCore GmbH & Co. KG - Thomas-Mann-Straße 8 - 22880 Wedel - Germany
