doctoolchain / doctoolchain Goto Github PK

When exporting to Confluence the "children" macro is added at the bottom of each page. The script doesn't specify any order explicitly and it seems "sort by title" is the default choice.

When using section numbers this starts to look weird as soon as you get to chapter 10 :-)

The other sort options are "creation" and "modification".

Given the way the script works, pages should get created in the same order they appear inside the document that is being exported. So maybe explicitly sorting by "creation" would be better?

The alternatives are "leave it as it is" and "make it configurable".

It would be great to have the plantUML source avaialble in Confluence and have Confluence render it (diagram plugin).
PlantUML stores the source within the generated images. So the solution could be to check if the image to be published is a plantUML one and then extract the soruces and replace the image with the source and plugin reference.

... but does it also run on a linux based os?

if a connector contains a note, this note is not exported

At the moment we have a really nested structure. I wondering if it wouldn't become more handy to have the following structure:

At top level

• src/doku and src/doc: based on the assumption that nobody writes a documentation in two languages and even if he does it's better to create than 2 git repos.
• under doku or doc only arc42, images and perhaps pdfTheme (even this is not really documentation it's more styling) and than no further nesting.

It's make it easier to delete all the stuff it's not necessary and easier to navigate.

if the password is blank, it should be read from the console. But the console input is never assigned

We just had a case where exporting one document "stole" a page from a different document because they happened to share the same title. We now made using confluencePagePrefix mandatory for us. The real problem is, we only noticed the problem by chance.

When the parentId is set pushToConfluence could verify the ancestor of the page it finds for a given title matches the parentId and either reject the exporting the page or at least print a warning.

we need some kinds of simple landing page which introduces all features with a sentence and links to some docs which explain how to use the feature.

the first doc should be a specialized html5 landing page.
the second doc could be written as asciidoc and could be the sample doc of the project.

Asciidoc can contain page breaks <<<<
It would be great if these could be used as markers to split long confluence pages into several pages

At the moment all arc42 hints are included. It would be nice to have the possibility to delete this via a task or strip this at generation.

@opensource21 : just gave it a try - a really great feature! I like the evaluation for formulars...

However, I would like to discuss three design decisions:

1. Naming: should we call it exportExcel or more generic name since I guess the POI code will also handle open office for example
2. output folder: shall we use the src or the build folder? I used for some tasks the src folder because the involved tools are not available on a build server (Windows/Linux problem). Afaik, POI will also run on a Linux machine and it is running really fast (doesn't have to start Excel), so it could make sense to use the build folder.
3. output format: csv works great, an asciidoc table could give us more freedom for extensions. For example, POI could read the alignment of the cell content and create corresponding markup

What do you think?

I wondering if you have a task which exports every sheet of excelfiles to csv, so that they can included into asciidoc.
Can you provide an idea how to add a gradle task to the project? Must there a task for maven too?

The jira export for open issues uses the gradle config properties for the configuration of the endpoint and user.
The publish to confluence tasks uses a config groovy script which is evaluated.
The jria to EA sync also uses a groovy script which is evaluated.

These three mechanism should be unified and brought together in one config file.

What's the pain?
If once configured, there is not much pain, but each new user of docToolchain has to go through the configuration process and this will be pain. Hard to put a figure on it, but if docToolchain want to be successfull, it should make itself as easy to use as possible.

...should be rendered as one. They just need the line break removed

• add htmlSanityChecker
• add workaround for missing includes: asciidoctor/asciidoctor-gradle-plugin#154
• add fix for data-urls in htmlSanityChecker

:data-uri:
http://asciidoctor.org/docs/user-manual/#managing-images

currently, the exportEAP task adds the name of the element on top of each exported note.
This makes it impossible to define a table with the note content of several elements.

The fix should check if the note starts with a pipe | and if so, recognize that this is a table row definition and should not add the element name on top of this note

all lines which start with a coment mark like "/" or "#" should be excluded.

There seems to be a problem with the first regexp introduced with #45 - it causes a stack overflow

java.lang.StackOverflowError
	at java.util.regex.Pattern$Neg.match(Pattern.java:5086)
	at java.util.regex.Pattern$Branch.match(Pattern.java:4604)
	at java.util.regex.Pattern$GroupHead.match(Pattern.java:4658)
	at java.util.regex.Pattern$Loop.match(Pattern.java:4785)
	at java.util.regex.Pattern$GroupTail.match(Pattern.java:4717)
	at java.util.regex.Pattern$BranchConn.match(Pattern.java:4568)
	at java.util.regex.Pattern$CharProperty.match(Pattern.java:3777)
	at java.util.regex.Pattern$Neg.match(Pattern.java:5097)
	at java.util.regex.Pattern$Branch.match(Pattern.java:4604)
...

with all lines I can get stemming from java.util.regex.Pattern - it is this one https://github.com/rdmueller/docToolchain/pull/45/files#diff-8e03331c0e61a64770510b8e9d5a7021R205

I'm trying to create a minimal document triggering the problem. It looks as if one needs two code blocks with language attributes on the same Confluence page. First suspect is the negative look ahead and I need to figure out why it is there before I try to fix it :-)

It might be possible to achieve the same effect by using JSoup rather than regexps.

If an element is a composite one and contains a subdiagram, this subdiagram and its elements is not exported

If a change is only make at a subdocument, for example the glossar, gradle thought that the output is newer than the input and do nothing.

asciidoctor generated HTML uses id attributes as anchors for links. When the pages get published to Confluence the ids get partly stripped and partly rewritten by Confluence so all anchors are lost. In addition the links themselves need to get rewritten as the content is now spread across multiple pages.

The code in https://github.com/bodewig/docToolchain/tree/internal_links gets pretty close but is not ready for a PR, yet.

What it does:

• add a Confluence anchor macro for every id attribute.
• keep track of the pages anchors appear on, also record anchors corresponding to the elements that now become page titles and no longer appear inside the DOM at all.
• replace all links whose hrefs start with # with Confluence link macros

I still need to take confluencePagePrefix into account, but this is trivial.

The Confluence link macro expects the link text to be inside a CDATA-section. I.e.

<ac:link ac:anchor="foo-anchor"><ri:page ri:content-title="1. Bar" /><ac:plain-text-link-body>Baz</ac:plain-text-link-body></ac:link>

renders a link with text "1. Bar#foo-anchor" while

<ac:link ac:anchor="foo-anchor"><ri:page ri:content-title="1. Bar" /><ac:plain-text-link-body><![CDATA[Baz]]></ac:plain-text-link-body></ac:link>

renders a link with text "Baz". We clearly want the latter.

Unfortunately I haven't found a way to tell JSoup I want a CDATA section and when I add it manually JSoup strips it (which is perfectly fine from an XML point of view). So I came up with the ugly hack of introducing my own cdata-placeholder element and replacing it when the DOM tree is rendered as a string. This feels wrong, better ideas are welcome.

CDATA also means you can't have HTML markup inside of your link text, it currently gets rendered escaped, i.e. "<code>Foo</code>" rather than "Foo" if you've used something like <<foo-anchor,`Foo`>> for your link. I plan to replace the innerHTML of the link I replace with its text, which would mean we lose styling but don't get to see literal content.

The branch currently also contains code I've later removed (rewriting a tags with name attributes as anchor macros as well, and not considering ids that start with a _). Should I rebase the branch to remove this intermezzo or even squash it to a single commit before I open a PR?

Also, is there a good place to add documentation at the same time? I think the effect of lost styling is something that may come as a surprise and should be documented somewhere.

If the case of a character in a headline is changed, the script searches for the new headline and doesn't find a page with this name (case sensitive search).
It then tries to create the corresponding page which leads to an "page already exists" error (case insensitive)

Solution: make the search for the page title case insensitive

It would be nice to be able to configure that the names of images exported from EA are replaced by "_" underscore.
So that it is easier to reference them in asciidoc

the task starts with the first chapter (level 1) and not with the first page (level 0)

see asciidoctor/asciidoctor-diagram#139

Right now when confluenceCreateSubpages is true all headlines get "promoted" to higher levels (i.e. h4 becomes h1 and so on). Shouldn't the same also be done for the pages created from h2 as well, just with one level less of promoting - i.e. h3 becomes h1 and so on?

I'll be happy to take a stab myself, Before I do so I just want to make sure the difference is not an intentional one.

when I switch the gradle build file from ruby asciidoctor extensions to asciidoctorj extensions, the jira inline extension breaks:

FAILURE: Build failed with an exception.

* Where:
Build file 'C:\Users\ralfd\projects\github\rdmueller\docToolchain\build.gradle' line: 57

* What went wrong:
Execution failed for task ':asciidoctor'.
> (NameError) cannot load Java class org.asciidoctor.groovydsl.extensions.DelegatingInlineMacroProcessor

• What went wrong:
  Execution failed for task ':exportChangeLog'.

.\build\docs\changelog.adoc (The system cannot find the path specified)

It is great to have all element notes of a kind exported to a file, but if those elements - like for instance actors - are used in different diagrams, I would like to have them grouped by diagram, too.

Here, I see two solutions:

a) save all notes of elements contained by the diagram in a file called "[digramName]_notes.adoc"
b) save all notes of elements contained by the diagram in several files grouped by the {adoc:x} tag of the elements eg "[digramName]_notes_x.adoc"
c) do the same for connectors

a definition list like this:

Definition::

a test

results in a malformed html:

Error parsing xhtml: Unexpected close tag </table>; expected </tr>.

<div class="dlist"> 
 <table><tr> 
  <tr><th>
   Definition
  </th> 
  <td> 
   <p>a test</p> 
  </td></tr> 
</table> 
</div> 

the build.gradle file grew by now to an enourmous size.

today I tried to use script plugins in order to create several modules. This seems to work great for most tasks, but it doesn't work for the htmlSanityCheck

create one. With issues and improvements...

If a table within an arc42 helptext contains tags, the closing tags are removed and thus the result is not xhtml conform. The build breaks because confluence rejects the non conform xHTML

how can the PDF header be set individually for each PDF?

is this already implemented?

the code still has some issues with empty cell... so make sure that all cells have at least an ' as content...

make all parameters overwriteable per input file (space, deep structure, credentials)

the heading level should start at 1 for all pages, no matter how deep they are nested

missing repositories and dependencies

Hi Ralf,

first: thanks for your amazing tool! I heard of this in a seminar of Dr. Starke and Dr. Hrushka and immediatly fall in love with it!

I tackeled down a very weird bug:

Precondition

Inside the arc42 documentation a code block declared like this:

[source,java]
----
public class Test {
}
----

Expectations

A nice rendered block of Java code.

Actual result

Error during the publishToConfluence task:

something went wrong - got an http response code 400:
[statusCode:400, data:[authorized:false, valid:true, errors:[], successful:false], message:Error parsing xhtml: String ']]>' not allowed in textual content, except as the end marker of CDATA section

Workaround

Remove java from the declaration. The declaration would look like this now:

[source]
----
public class Test {
}
----

Then, everything works fine.

--

If you can show me where to fix this, I can try. Or if you need additional information or anything, let me know. Thanks again for this awesome tool!

When using inline comments in confluence, a new publishToConfluence overwrites these comments.

Inline comments are stored in confluence like this:

<p>Lorem <ac:inline-comment-marker ac:ref="e8e647e6-b612-4123-b1bb-3f5fd6d89c10">Ipsum</ac:inline-comment-marker> etc.</p>

So, it should be possible to at least notice them, maybe even keep them.

If I use

        'pdf-stylesdir': 'pdfTheme',
            'pdf-style': 'custom',

I get the following errors:

The following text could not be fully converted to the Windows-1252 character set:
| ?
(ArgumentError) uri:classloader:/gems/asciidoctor-pdf-1.5.0.alpha.15/data/fonts/OpenSansEmoji.ttf not found
:generatePDF FAILED

It looks like the font must be adjusted, but I'm unsure how.

See asciidoctor/asciidoctorj#389 and asciidoctor/asciidoctor-pdf#409

definition lists are rendered incorrect as one single table row. should be rendered as one row per definition

When publishing to Confluence we'd like to include a "Do not edit this page" warning macro to every page created.

I'll open a pull request that allows an optional extra content to be configured.