Newbie question: Can snippet contents be retained after snippets deleted?

[lhartzman]

Hi,

Just started using Asciidoctor in conjunction with Spring-restDocs. I'm using the include directive to add the snippets to the main document file, but if the snippets are cleared out, I'm left with unresolved includes in the master document.

Is there a way to specify that the contents of the snippets be extracted and placed in the master document? If I picked PDF or HTML generation, would it happen for those formats? Currently sticking with adoc format.

Thanks.

Les

[mojavelinux]

There is a coalescer script that does roughly this. It "reifies" the includes, effectively expanding them inline.

See https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb

The script may need some work, so feel free to submit a patch if you can improve it.

Cheers,

-Dan

On Fri, Dec 4, 2015 at 5:22 PM, lhartzman [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

Just started using Asciidoctor in conjunction with Spring-restDocs. I'm using the include directive to add the snippets to the main document file, but if the snippets are cleared out, I'm left with unresolved includes in the master document.

Is there a way to specify that the contents of the snippets be extracted and placed in the master document? If I picked PDF or HTML generation, would it happen for those formats? Currently sticking with adoc format.

Thanks.

Les

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Newbie-question-Can-snippet-contents-be-retained-after-snippets-deleted-tp4018.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

[lhartzman]

Thanks! I'll take a look at the script.

Les

[lhartzman]

I tried running the script from the command line and I get repeated warnings:

ruby asciidoc-coalescer.rb API_doc.adoc  produces:

asciidoctor: WARNING: include file has illegal reference to ancestor of jail, auto-recovering
asciidoctor: WARNING: API_docs.adoc: line 664: include file not found: {full path of file - and it exists}

for all included snippet files.

If I run asciidoctor API.doc.adoc, I get the expected HTML file. So if finds the included snippet files.

I'm sure this is operator error (well, I'm hoping it's operator error!)

Les

[mojavelinux]

You seem to have an include path that is outside of the base directory. To fix that, you could try changing the safe mode in the file. Look for

safe: :safe

and change it to 

safe: :unsafe

To know more, I'd have to see the files you are working on or an example that demonstrates the same behavior.

Cheers,

-Dan

On Thu, Jan 14, 2016 at 5:23 PM, lhartzman [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I tried running the script from the command line and I get repeated warnings:

ruby asciidoc-coalescer.rb API_doc.adoc  produces:

asciidoctor: WARNING: include file has illegal reference to ancestor of jail, auto-recovering
asciidoctor: WARNING: API_docs.adoc: line 664: include file not found: {full path of file - and it exists}

for all included snippet files.

If I run asciidoctor API.doc.adoc, I get the expected HTML file. So if finds the included snippet files.

I'm sure this is operator error (well, I'm hoping it's operator error!)

Les

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Newbie-question-Can-snippet-contents-be-retained-after-snippets-deleted-tp4018p4191.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

[lhartzman]

I put the 'unsafe' attribute value in the file (there wasn't any 'safe' attribute in there before. Same errors.

My directory structure looks like this:

<project-dir>
     <Service>
          <build>
             <generated-snippets>
                 <REST-controller1>
                      <Create>                       <<--- these directories are actually multi-word names with spaces (replaced spaces
                                                                      with hyphens, but made no difference)
                         curl-request.adoc
                         http-request.adoc
                         http-response.adoc
                     <Get>
                         ...
                     <Delete>
                        ....
          <Docs>
                API_doc.adoc
                API_doc.html
                asciidoctor-coalescer.rb


Here is a sample of the file:

safe: :unsafe

= *REST API*

== *Overview*

This document describes the REST API.

:toc:
:experimental:
:blankline: pass:[ +]
:setanchors
:sectlinks:

{blankline}
{blankline}

NOTE: request body parameters need to be encoded as kbd:[JSON].

[[verbs]]
== *HTTP Verbs Used*

[cols="1,2"]
|===
|GET
|retrieve resource

|CREATE
|add new resource

|PUT
|update existing resource, replacement or partial update.

|DELETE
|delete resource
|===

[[headers]]
== *Request Headers*
[cols="3,4", options="header"]
|===
|Header
|Value

|MccUsername
|

|Content-Type
|application/json
|===


[[account]]
== *Account API*
=== */accounts/{accountId}*

[[account_fields]]
=== Fields
[cols="1,1,6,3,4", options="header"]
|===
|Name
|Type
|Values
|Default
|Description

|name | String |N/A|N/A| *Not null*
|companyName | String |N/A| null | Optional company name
|canManageClients | Boolean | true{vbar}false | false | Whether this account can manage clients
|===
{blankline}
[[account_create]]
*CREATE:* _Create an account_

.Sample request and response

//include::{snippets}/AccountController/Creates-an-account-for-publisher/http-request.adoc[]   couldn't get {snippets} to be accepted.

include::../build/generated-snippets/AccountController/Creates-an-account-for-publisher/http-request.adoc[]
include::../build/generated-snippets/AccountController/Creates-an-account-for-publisher/http-response.adoc[]