-
Notifications
You must be signed in to change notification settings - Fork 179
Asciidoc Cleanup #170
Comments
Not sure about this. Seems to expect "section headers" to always follow 1-2-3. But some are really just what size of title (h1, h2, h3) do you want. pandoc just copies over what is in the html. so, can we set header size independent of the section numbering? |
Yeah, I'd argue that choosing the heading level based purely for font size is the precisely the wrong thing to do. Use the proper semantic meaning in the markup (html/asciidoc), then use the stylesheet (CSS) to control the appearance. |
so, can we set header size independent of the section numbering? |
Well, you can easily set the font size of all |
Hi all, I updated the css to use what asciidoctor produces in terms of html tags and changed UpgradingTo5.adoc to use it. Here is what the page looked like before using the asciidoc specific css: http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/UpgradingTo5-old.html and here is what it looks like using the asciidoc specific css file (tds_adoc.css): http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/UpgradingTo5.html At some point I need to run this by @oxelson and @ddirks to get their input, as I am sure I've missed a few things in the new css file. I can also make a pull request on 5.0 to move over the new css file as well as the adoc and html for the UpgradingTo5 page; currently, this lives on a branch under my account. |
I'm okay with the 2nd version (it fits the Unidata "theme"), but we're not On Mon, Sep 21, 2015 at 10:59 AM, Sean Arms [email protected]
|
Ok, check it out again. I've added syntax highlighting via pygments, but that means in order to build the docs, you will need both asciidoctor as well as pygments (both python and ruby libs). Note that pygments is only compatible with python 2.7 at the moment, but they are working on compatibility for version 3. |
Given those extra dependencies, I don't think that AsciiDoc-with-pygments can be built by JRuby. That's going to be a problem down the line when we're rendering the AsciiDoc from Gradle, as that all relies on JRuby. Here is an example using |
Thanks for the heads-up @cwardgar! I moved UpgradingTo5.adoc to use coderay. It's not too bad, actually. We could customize the color scheme if we wanted to do so, but any highlighting is better than no highlighting. |
I've updated all of the asciidoc files on 5.0 under docs/website/tds to use the following: :source-highlighter: coderay |
Results of my most-recent run:
Seems like a lot of boring formatting errors that cropped up during the HTML -> AsciiDoc mass-conversion. We should all start chipping at away at these, like we did the Coverity defects. |
I'll take a look, and I'll work in knocking down the ERROR messages this evening. The warnings are a more work, but maybe I can get it done this week, 🍺 willing. |
doesnt seem too bad. GribNotes is internal and can be ignored. ill fix it can we get this html out onto the web and replacing the current 5.0 docs, On Mon, Jan 11, 2016 at 8:49 AM, Sean Arms [email protected] wrote:
|
Hi John, I can start pushing the html files (converted from adoc) to the main Cheers, Sean On Sun, Jan 17, 2016 at 11:06 AM, John Caron [email protected]
|
any improvements to css? http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/UpgradingTo5.html looks pretty bad from my aesthetic POV. On Mon, Sep 21, 2015 at 6:59 AM, Sean Arms [email protected] wrote:
|
Can you be more specific? I clicked the link expecting an eyesore, but was pleasantly surprised. It's not perfect, but I'd be hard-pressed to actually say how I would make it better. |
pretty much all the differences from http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/UpgradingTo5-old.html except for the double header On Fri, Jan 29, 2016 at 8:30 AM, Ryan May [email protected] wrote:
|
Hi John, all: I just moved over the 5.0 asciidoctor -> html docs to the top level tds: http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/TDS.html The old, non-asciidoctor docs are backed-up here: tds: http:https://www.unidata.ucar.edu/software/thredds/v5.0/bkup/tds/TDS.html How does the asciidoctor -> html version look: http:https://www.unidata.ucar.edu/software/thredds/v5.0/bkup/tds/UpgradingTo5.html compared to the old version: http:https://www.unidata.ucar.edu/software/thredds/v5.0/bkup/tds/UpgradingTo5-old.html I know some of the links are not working correctly, but I have a PR on Sean On Fri, Jan 29, 2016 at 11:39 AM, John Caron [email protected]
|
In my opinion, the version with AsciiDoctor's default CSS is the best-looking: http:https://www.unidata.ucar.edu/software/thredds/v5.0/bkup/tds/UpgradingTo5-old.html. Unfortunately, it doesn't really fit the new Unidata theme. The workshop-style CSS (http:https://www.unidata.ucar.edu/software/thredds/v5.0/bkup/tds/UpgradingTo5.html) isn't too bad, but I really dislike the boxing of sections. The Unidata theme already forces us into a narrow column and that CSS needlessly wastes even more space, both horizontally and vertically. |
am i the only one who dislikes? the border around the sections, the lack of shading, the fonts and font for links, can you remind me what they should look like or point to a thanks On Fri, Jan 29, 2016 at 12:00 PM, Sean Arms [email protected]
|
I like the "old" one better--but we're pretty hamstrung here by fitting within the master CSS for UCAR/Unidata. Do we have any options here? We could always move to github.io..... |
Or host it on S3. Any time we move one of our products or some aspect of our workflow off UCAR servers, I'm a happy guy. |
Hi all, I'm ok with either version, and certainly not stuck on one over the other. Sean
On Sun, Jan 31, 2016 at 3:57 PM, Christian W [email protected]
|
Hi all, Sorry, I've not been watching this thread or would have chimed in sooner. It's my hope that we can come up with a stylesheet that is broadly useful for all Unidata software documentation, looks good, and integrates itself tolerably with the Unidata web site styling. This doesn't mean it has to look the same as the more general pages, only that the designs should mesh reasonably well. (If you'll recall, we're working under something of a mandate that the web site use -- or at least not clash with -- a UCAR-wide design template.) I'm cognizant that the "we" at the beginning of the last paragraph really means that I have to make more of an effort to create space in my schedule to actually do this, rather than just saying "we should do that" as I have been pretty much since Sean showed me the asciidoc stuff. My bad, but it just hasn't come to the top of the priority list. I'm still working on the NSF annual report, but that's easing off and with luck I can focus on writing a style sheet Real Soon Now. Just so you know, Ward has approached me regarding the styling of the netCDF docs, so that's an additional prod to get me to prioritize this. -=DD=- |
Any progress? |
Hi John, This is going to be my focus as I recover from surgery over the next few Sean On Saturday, July 30, 2016, John Caron [email protected] wrote:
|
Many warnings when converting asciidoc files to html regarding headings / sections out of sequence.
If you are the owner of one of these files
please update with the correct sequence. For documentation on the correct sequence, please see http:https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#section-titles
The text was updated successfully, but these errors were encountered: