Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
Although it's been out for a few days, I'm still thrilled (and still feeling relieved) to announce the release of Asciidoctor 0.1.4! Why so relieved? Well, it was a long road to make good on promises like extensions :)Asciidoctor 0.1.4 was originally planned to be a small release. Instead, it turned out to be a summer-long project, spanning from Memorial Day to Labor Day. The result? The biggest release yet. Ninety issues — that’s right, 90 — were closed along the way, resulting in 325 commits. The extended development cycle was due in part to a major pickup in the amount of feedback from the community. We also didn’t want to let another release slip by without including an extension mechanism, which we’re happy to say is available in this release as a technology preview. Want to find out more? Well, you won't be disappointed by the depth of this post / release notes, to which a lot of credit goes to Sarah White for rounding up the information and working with (and pushing) me to revise it :) http://asciidoctor.org/news/2013/09/05/asciidoctor-0-1-4-released/ If you're in a hurry, here's the TL;DR version: * Stylesheets are embedded by default * Inter-document cross references (e.g., <<doc-b#section-a,Section A in Document B>>) * Implicit header row on tables * DocBook 5.0 backend (i.e., docbook5) * Icon inline macro (e.g, icon:heart[2x]), designed primarily for using font-based icons * Checklists * Developer and user-friendly callouts in code listings * Pygments syntax highlighter (e.g., source-highlighter=pygments) * Shorthand notation for block options (e.g., [%header%footer]) * Shorthand notation for id and role on formatted text (e.g., [#id.role]_text_) * Roles for text enclosed in backticks (e.g., [role]`text`) * Docinfo files for the document footer (e.g., docinfo-footer.(html|xml)) * Include file from URL using include::[] directive * Include file is resolved relative to current include file * Support for YouTube and Vimeo IDs in video macro (e.g., video::12345[youtube,480,360]) * Missing attribute references (e.g., {bogus}) do not cause line to be dropped (by default) * Parse manpage metadata * TOC positioning (e.g., toc-position=right, toc=right or toc2=right) * Improved section numbering in document and in TOC * First draft of the Asciidoctor User Manual * Debian and Ubuntu packages (joining the Fedora package) We also have an official changelog too, finally: https://raw.github.com/asciidoctor/asciidoctor/master/CHANGELOG.adoc
There is so much exciting work ahead and I can't wait to get back to it. Thanks to all of you who help to make Asciidoctor awesome and documentation not suck. Cheers! -Dan |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
15 posts
|
Jeez, you get stuck doing actual company work and taking a bit of leave with the family and look what happens - AWESOME!
Well done Dan and everyone else who contributed. With luck, I can spend some cycles on the next release. |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
11 posts
|
In reply to this post by mojavelinux
I'm having trouble getting TOC positioning to work. I haven't found a toc or toc2 value that changes the default behavior, to render the TOC at the top of the document.
macbook:setting-world-fire neontapir$ asciidoctor --version Asciidoctor 0.1.4 [http://asciidoctor.org] macbook:setting-world-fire neontapir$ asciidoctor -a toc2=left setting-world-on-fire.asc However, it should be noted that when I run the same file through AsciiDoc, the table of contents is in a pane on the left as expected. macbook:setting-world-fire neontapir$ asciidoc -a toc2 setting-world-on-fire.asc Am I doing something unusual, or should I report this as an issue? Regards, Chuck |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
Chuck, I get the sense that there is a misunderstanding about where the TOC is expected to appear. I updated the Asciidoctor themes site so that it demonstrates the two sidebar TOC position options:http://themes.asciidoctor.org/preview/ The only other position that the Asciidoctor stylesheets support is inside the document (under the header, in the preamble or manually placed). With Asciidoctor 0.1.4, you should be able to place the toc on the left using: -a toc=left and on the right using -a toc=right Note, however, that the sidebar positioning depends entirely on the stylesheet. In fact, the TOC doesn't actually move at all. It just gets the hint from the style class that the CSS should be applied to make it shift to the left or right. FYI: The way the TOC is handled between Asciidoctor and AsciiDoc is quite different. AsciiDoc uses JavaScript to render the TOC after the page has loaded. Asciidoctor puts the stylesheet in the HTML of the page...and does so using different HTML markup (an unordered list) compared to AsciiDoc. Let me know if you need more input. I hope your next attempt is a successful one! On Tue, Sep 10, 2013 at 8:58 PM, neontapir [via Asciidoctor :: Discussion] <[hidden email]> wrote: I'm having trouble getting TOC positioning to work. I haven't found a toc or toc2 value that changes the default behavior, to render the TOC at the top of the document. ... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
In reply to this post by neontapir
I meant to add that while Asciidoctor recognizes the "top" and "bottom" positions, the stylesheet does not yet provide any styles to support these options. What I envision is using the topbar / bottombar components in Foundation (the CSS framework) to float the stylesheet horizontally in these cases. -DanOn Wed, Sep 11, 2013 at 3:52 AM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
11 posts
|
In reply to this post by mojavelinux
Interesting. In Chrome 29.0.1547.65 on my Mac, none of the themes show any noticeable difference. The effect I'm trying to achieve is the one provided by AsciiDoc with -toc2, which is to have the TOC rendered in a sidebar on the left. It doesn't appear that any of the Asciidoctor-provided themes offer that capability. I'll have to continue experimenting.
Thank you for the quick reply!
Chuck
On Wed, Sep 11, 2013 at 3:54 AM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
25 posts
|
Hi Chuck,
I'm also using Chrome. I followed the theme preview link Dan posted. The first theme, Asciidoctor, with the toc positioned to the left (see the little drop down menu in the right bottom corner of the image) shows up this way in Chrome for me: When I select "right" in the drop down menu, it moves to the right, as seen in the image below: If Chrome is not displaying this change when you toggle between the themes and toc placements on the showcase page, we've definitely got some debugging to do . Next up, the default behaviour of toc2 in Asciidoctor should be the same as in AsciiDoc; therefore, you should just have to set the attribute as :toc2:. You do not need to add the value of 'left'. (On a side note, setting :toc2: is the same as setting :toc: left). Let me know if the theme showcase isn't showing you images like the ones I embedded above, and if when you set :toc2: it does not display the ToC as a sidebar on the left. We'll get to the bottom of this ! -Sarah |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
11 posts
|
I'm seeing the correct behavior now on the sample site (whew!), but I didn't last night when I posted. When I get home, I'll retry my document generation and see if I obtain similar success. Thanks, Sarah! On Wed, Sep 11, 2013 at 9:34 AM, graphitefriction [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi Chuck, ... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
Aha! I finally figured out why we are seeing different results. I was leaving out an important piece of information when communicating how the sidebar works. The sidebar is "responsive", which means it behaves differently depending on the screensize. Below the "break point" width (1280px), the sidebar gives up its position and returns to the flow of the document (center position). I'm almost certain your screen at home, or the width of the browser window on that screen, is below the break point. Here's the definition in the stylesheet that controls this behavior: ```css @media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; } #toc.toc2 { position: fixed; width: 20em; left: 0; top: 0; ... } ... } ``` We may decide that this break point is too soon, or just slim down the sidebar below 1280px and return it to the center at the next lower width (break point). If you want to change this behavior, you can copy the toc2 styles into a docinfo.html file and modify the min-width [1]. That should override the behavior. You can also build a stylesheet to your liking using the stylesheet factory [2]. I'm so glad that we had this discussion because this is absolutely a missing piece of information in the documentation. Thanks! [1] http://asciidoctor.org/docs/user-manual/#docinfo-files [2] http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/ On Wed, Sep 11, 2013 at 12:47 PM, neontapir [via Asciidoctor :: Discussion] <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
In reply to this post by neontapir
I think we should make this change in Asciidoctor. I propose between 768px and 1280px (the two desktop-size break points in the Foundation framework), we shrink the width of the sidebar by 5em, reduce the list indentation by .25em and reduce the font-size by 10%. That way, the sidebar will fit reasonably well and there is limited chance for horizontal scrolling in the main content. Down the road, I'd like for us to implement a mobile sidebar like in Cardinal CSS [1].On Wed, Sep 11, 2013 at 1:48 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
11 posts
|
In reply to this post by mojavelinux
Yes, I think that's it! I am testing at under 1280px. Would it be worth making that value configurable? Thanks, On Sep 11, 2013 1:49 PM, "mojavelinux [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
... [show rest of quote] If you reply to this email, your message will be added to the discussion below:
To start a new topic under Asciidoctor :: Discussion, email [hidden email] To unsubscribe from Asciidoctor :: Discussion, click here. NAML -- Dan Allen | http://google.com/profiles/dan.j.allen
If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoctor-0-1-4-is-released-tp553p570.html
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
As I mentioned in the issue, I think the best solution is just to make it work on the medium resolution slightly scaled down. Of course, it can always be customized further by providing overrides to the stylesheet. The default stylesheet is really just the "out of box" behavior. I expect that anyone publishing docs will eventually tweak the stylesheet to their liking and color scheme. I recognize the docs for using the stylesheet factory still have a ways to go to make that a comfortable process, but it's certainly our goal to make it simple. On Wed, Sep 11, 2013 at 4:45 PM, neontapir [via Asciidoctor :: Discussion] <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
In reply to this post by neontapir
Btw, here's the issue I filed for this enhancement: -Danhttps://github.com/asciidoctor/asciidoctor/issues/628 On Fri, Sep 13, 2013 at 6:43 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
5 posts
|
In reply to this post by mojavelinux
Any idea on how to use Asciidoctor 0.1.4 with the maven plugin ?
Seems the plugin is still stuck at 0.1.3.1. |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
46 posts
|
I have heard from Jason (that I met here at Devoxx) that it would be published (very) soon.
Compiling the 0.1.4-SNAPSHOT works and solved my docbook5 backend issue. I am waiting for the release plugin to be available so that I can organize demo's at the office. Jmm |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
46 posts
|
the "it" beeing the asciidoctor maven plugin
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
5 posts
|
Cool, at first I thought it was Jason who was going to be published very soon
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
354 posts
|
There are a https://github.com/asciidoctor/asciidoctor-maven-plugin/issues?milestone=7&state=open[number of open issues] I would love to complete before I release, but if people are asking for it NOW, I can certainly release what's there and do those for a 0.1.4.1 release. Call to action: Help me finish bugs please :) On Thu, Nov 14, 2013 at 10:38 AM, wdrai [via Asciidoctor :: Discussion] <[hidden email]> wrote: Cool, at first I thought it was Jason who was going to be published very soon |
Free forum by Nabble | Edit this page |