tips/tools for ReSpec-to-Bikeshed conversion?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

tips/tools for ReSpec-to-Bikeshed conversion?

Hodges, Jeff
Hey guys, 

might any of y'all have any tips (or tools :)  for undertaking spec source conversion from ReSpec to Bikeshed?

thx

=JeffH

Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Tab Atkins Jr.
On Fri, Mar 4, 2016 at 11:46 AM, Hodges, Jeff <[hidden email]> wrote:
> Hey guys,
>
> might any of y'all have any tips (or tools :)  for undertaking spec source
> conversion from ReSpec to Bikeshed?

I haven't actually done a ReSpec conversion yet, but I'd be happy to
do one for you and write up the results into a helpful guide. ^_^

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Shane McCarron
In general we have tried hard to make the low level stuff compatible, so it should "just work". 

On Fri, Mar 4, 2016 at 1:58 PM, Tab Atkins Jr. <[hidden email]> wrote:
On Fri, Mar 4, 2016 at 11:46 AM, Hodges, Jeff <[hidden email]> wrote:
> Hey guys,
>
> might any of y'all have any tips (or tools :)  for undertaking spec source
> conversion from ReSpec to Bikeshed?

I haven't actually done a ReSpec conversion yet, but I'd be happy to
do one for you and write up the results into a helpful guide. ^_^

~TJ




--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Hodges, Jeff
In reply to this post by Tab Atkins Jr.
On 3/4/16, 11:58 AM, "Tab Atkins Jr." <[hidden email]> wrote:

On Fri, Mar 4, 2016 at 11:46 AM, Hodges, Jeff <[hidden email]> wrote:
Hey guys,

might any of y'all have any tips (or tools :)  for undertaking spec source
conversion from ReSpec to Bikeshed?

I haven't actually done a ReSpec conversion yet, but I'd be happy to
do one for you and write up the results into a helpful guide. ^_^

Hey Tab, thx for the generous offer -- perhaps we could work together on it in some fashion?   I welcome the learning curve wrt bikeshed.  :)

=JeffH

Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Hodges, Jeff
In reply to this post by Shane McCarron

> On Fri, Mar 4, 2016 at 11:46 AM, Hodges, Jeff <[hidden email]>
>wrote:
>>Hey guys,
>>
>>might any of y'all have any tips (or tools :)  for undertaking spec
>>source
>>conversion from ReSpec to Bikeshed?

On 3/4/16, 12:01 PM, "Shane McCarron" <[hidden email]> wrote:
>In general we have tried hard to make the low level stuff compatible, so
>it should "just work".

well, blow me down, it basically does "just work".

below's what it took to get initial readable output -- I haven't yet gone
through and de-HTML-ized and bikeshed-ized the spec source though (which
seems like something one would want to do).

hth,

=JeffH
------

I began with rendered ReSpec output file "Overview.html" (because that's
what we have access to at this time) -- copied that file to a new file
named "index.src.html" in same directory

did `bikeshed -f spec index.src.html`

got some error msgs, and NO index.html was output :(


added metadata section to index.src.html per initial example in
https://github.com/tabatkins/bikeshed/blob/master/docs/metadata.md, then..

did `bikeshed -f spec index.src.html`

got lots of error msgs including FATAL ones...tho it yielded "index.html"
-- loaded that in browser and it's readable :)

then..

edited index.src.html again:
  deleted <style>...</style>  (this was rendered respec style block)
  added "title:" to metadata

did `bikeshed -f spec index.src.html`


index.html now only rendered front matter thru Abstract and ToC header,
nothing after that except References header

installed pygments per one of the bikeshed error msgs

did `bikeshed -f spec index.src.html`


that yielded MUCH fewer error msgs, just these..

FATAL ERROR: Found unmatched text macro [DOM4]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [HTML5]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [RFC2119]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [PSL]. Correct the macro, or
escape it with a leading backslash.

..but index.html again only rendered front matter thru Abstract and ToC
header, nothing after that except References header


so I did s/[...]/\[...]/  for all four of above items (by hand) -- I found
them down within..

<section property="bibo:hasPart" resource="#references"
typeof="bibo:Chapter" id="references" class="appendix">

..near end of file


did `bikeshed -f spec index.src.html`

it ran w/o errors but index.html again only rendered front matter thru
Abstract and ToC header, nothing after that except References header

so I edited index.src.html again and deleted..

<h1 class="title p-name" id="title" property="dcterms:title">FIDO 2.0: Web
API for accessing FIDO 2.0 credentials</h1>
 
  deleted:  <script type="application/json" id="initialUserConfig">{
  "specStatus": "Member-SUBM",
  "specVersion": "v2.0",
  "shortName": "fido-web-api",
  "publishDate": "2015-11-20",
  "copyrightStart": "2013",
  "editors":  ........
  }</script>


did `bikeshed -f spec index.src.html`

got both warnings and errors  and the full spec rendered in index.html  --
good enough for now

end





Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Tab Atkins Jr.
On Mon, Mar 7, 2016 at 4:43 PM, Hodges, Jeff <[hidden email]> wrote:
> installed pygments per one of the bikeshed error msgs

It sounds like you didn't follow the installation instructions
<https://github.com/tabatkins/bikeshed/blob/master/docs/install.md>
linked from the README.  You're probably fine by now, but I find that
people often run into problems because they cowboy'd the installation
and missed some important steps. ^_^

> FATAL ERROR: Found unmatched text macro [DOM4]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [HTML5]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [RFC2119]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [PSL]. Correct the macro, or
> escape it with a leading backslash.

These are because strings like "[FOO]" are recognized by Bikeshed as
text macros, which get substituted with something else at run-time.
For a biblio reference, you want to double up on the brackets, to get
"[[DOM4]]", etc.  This is described in
<https://github.com/tabatkins/bikeshed/blob/master/docs/markup.md#autolink-shortcuts>.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Shane McCarron
I would have started with the respec INPUT, not the output.  But otherwise I am happy it seemed simple.

On Mon, Mar 7, 2016 at 6:55 PM, Tab Atkins Jr. <[hidden email]> wrote:
On Mon, Mar 7, 2016 at 4:43 PM, Hodges, Jeff <[hidden email]> wrote:
> installed pygments per one of the bikeshed error msgs

It sounds like you didn't follow the installation instructions
<https://github.com/tabatkins/bikeshed/blob/master/docs/install.md>
linked from the README.  You're probably fine by now, but I find that
people often run into problems because they cowboy'd the installation
and missed some important steps. ^_^

> FATAL ERROR: Found unmatched text macro [DOM4]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [HTML5]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [RFC2119]. Correct the macro, or
> escape it with a leading backslash.
> FATAL ERROR: Found unmatched text macro [PSL]. Correct the macro, or
> escape it with a leading backslash.

These are because strings like "[FOO]" are recognized by Bikeshed as
text macros, which get substituted with something else at run-time.
For a biblio reference, you want to double up on the brackets, to get
"[[DOM4]]", etc.  This is described in
<https://github.com/tabatkins/bikeshed/blob/master/docs/markup.md#autolink-shortcuts>.

~TJ



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Hodges, Jeff
On 3/8/16, 5:13 AM, "[hidden email] on behalf of Shane McCarron" <[hidden email] on behalf of [hidden email]> wrote:

I would have started with the respec INPUT, not the output. 

well, that was what was conveniently lying around....but i did root around and find respec source and tried that and my impression was that bikeshed was even more unhappy with that.  


=JeffH

Reply | Threaded
Open this post in threaded view
|

Re: tips/tools for ReSpec-to-Bikeshed conversion?

Hodges, Jeff
In reply to this post by Tab Atkins Jr.
On 3/7/16, 4:55 PM, "Tab Atkins Jr." <[hidden email]> wrote:

On Mon, Mar 7, 2016 at 4:43 PM, Hodges, Jeff <[hidden email]> wrote:
installed pygments per one of the bikeshed error msgs

It sounds like you didn't follow the installation instructions
linked from the README.  You're probably fine by now, but I find that
people often run into problems because they cowboy'd the installation
and missed some important steps. ^_^

AFAIK I correctly followed the installation.



FATAL ERROR: Found unmatched text macro [DOM4]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [HTML5]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [RFC2119]. Correct the macro, or
escape it with a leading backslash.
FATAL ERROR: Found unmatched text macro [PSL]. Correct the macro, or
escape it with a leading backslash.

These are because strings like "[FOO]" are recognized by Bikeshed as
text macros, 

yeah, they're in there cuz i fed poor bikeshed respec output which contains what it thinks are macros (they're citations)

in any case, further munging of the input with a regex-capable editor will likely smooth things out. 

thx

=JeffH