Creating a visible Revision History

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

Creating a visible Revision History

Patrick Ben Koetter
Greetings!

First of all thank you very much for all the great work you've put into asciidoctor. I'm a long time asciidoc user and you've really taken the subject a significant step further.

I'm trying to place a visible revision history at the beginning of a book. Searching the archives I found references suggesting I should create an XML file (just like in asciidoc). This file should be named like the book, but have an additional suffix "-docinfo.xml".

I did so, but asciidoctor doesn't seem to embed the contents of the docinfo file. Is there any additional switch/option I need to set? Here's what I did to verify procedure...

I've created a book.adoc file and added these attributes:

----
Book
====
:doctype: book
:docinfo: private
----

Then I created a dook-docinfo.xml file, containing this dataset:

----
<revhistory>
  <revision>
    <revnumber>0.01</revnumber>
    <date>2018-11-22</date>
    <authorinitials>PBK</authorinitials>
    <revremark>
        First remark
    </revremark>
  </revision>
  <revision>
    <revnumber>0.02</revnumber>
    <date>2018-11-23</date>
    <authorinitials>PBK</authorinitials>
    <revremark>
        Another remark
    </revremark>
  </revision>
</revhistory>
----

Finally I used this command to proecess the asciidoc file and have it create HTML output:

$ asciidoctor book.adoc

But the only file that holds the string remains book-docinfo.xml:

$ grep PBK book*
book-docinfo.xml:    <authorinitials>PBK</authorinitials>
book-docinfo.xml:    <authorinitials>PBK</authorinitials>

Am I doing it wrong?

Thanks,

p@rick

$ asciidoctor -V
Asciidoctor 1.5.8 [https://asciidoctor.org]
Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
Reply | Threaded
Open this post in threaded view
|

Re: Creating a visible Revision History

mojavelinux
Administrator
Patrick,

The docinfo file you created is for DocBook output, but you are creating an HTML document. You either need to create a DocBook file:

asciidoctor -b docbook book.adoc

or you need to make a docinfo file for HTML named book-docinfo.html.

Asciidoctor is simply injecting the docinfo content into the output document.


Cheers,

-Dan

On Fri, Nov 23, 2018 at 9:44 AM Patrick Ben Koetter [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Greetings!

First of all thank you very much for all the great work you've put into asciidoctor. I'm a long time asciidoc user and you've really taken the subject a significant step further.

I'm trying to place a visible revision history at the beginning of a book. Searching the archives I found references suggesting I should create an XML file (just like in asciidoc). This file should be named like the book, but have an additional suffix "-docinfo.xml".

I did so, but asciidoctor doesn't seem to embed the contents of the docinfo file. Is there any additional switch/option I need to set? Here's what I did to verify procedure...

I've created a book.adoc file and added these attributes:

----
Book
====
:doctype: book
:docinfo: private
----

Then I created a dook-docinfo.xml file, containing this dataset:

----
<revhistory>
  <revision>
    <revnumber>0.01</revnumber>
    <date>2018-11-22</date>
    <authorinitials>PBK</authorinitials>
    <revremark>
        First remark
    </revremark>
  </revision>
  <revision>
    <revnumber>0.02</revnumber>
    <date>2018-11-23</date>
    <authorinitials>PBK</authorinitials>
    <revremark>
        Another remark
    </revremark>
  </revision>
</revhistory>
----

Finally I used this command to proecess the asciidoc file and have it create HTML output:

$ asciidoctor book.adoc

But the only file that holds the string remains book-docinfo.xml:

$ grep PBK book*
book-docinfo.xml:    <authorinitials>PBK</authorinitials>
book-docinfo.xml:    <authorinitials>PBK</authorinitials>

Am I doing it wrong?

Thanks,

p@rick

$ asciidoctor -V
Asciidoctor 1.5.8 [https://asciidoctor.org]
Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Creating a visible Revision History

Patrick Ben Koetter
Dan,

thank you for taking the time to answer my question.

I don't believe this will get me closer to my goal. What I want is *visible*
content, e.g. a table, that holds information like this:

                    Versionhistory
Release     Date        Description                 Name
0.3         28.06.2017  Dokumentreview und          PBK
                        Ergänzung für Erarbeitung
                        eines Gestaltungkatalogs.
0.2         August 2015 Added new sections with     PBK
                        cover page, automated SVG
                        and GIF conversion and
                        diagrams
0.1         August 2015 Initial version             PBK

IIRC DocBook provides this via book-revhistory.xml and – my memory may serve
me wrong – I think asciidoc (Python) was able to handle this as well.

asciidoctor allows me to use *-docinfo.html, but this will only let me add
content into the head-section:

- <base>
- <link>
- <meta>
- <noscript>
- <script>
- <style>

If there's no mechanism in asciidoctor at the moment to help me do that I will
simply use a table and add that to my documents. No need to bother, then.

Cheers,

p@rick



* mojavelinux [via Asciidoctor :: Discussion] <[hidden email]>:

>
>
> Patrick,
>
> The docinfo file you created is for DocBook output, but you are creating an
> HTML document. You either need to create a DocBook file:
>
> asciidoctor -b docbook book.adoc
>
> or you need to make a docinfo file for HTML named book-docinfo.html.
>
> Asciidoctor is simply injecting the docinfo content into the output
> document.
>
> See https://asciidoctor.org/docs/user-manual/#docinfo-file for details.
>
> Cheers,
>
> -Dan
>
> On Fri, Nov 23, 2018 at 9:44 AM Patrick Ben Koetter [via Asciidoctor ::
> Discussion] <[hidden email]> wrote:
>
> > Greetings!
> >
> > First of all thank you very much for all the great work you've put into
> > asciidoctor. I'm a long time asciidoc user and you've really taken the
> > subject a significant step further.
> >
> > I'm trying to place a visible revision history at the beginning of a book.
> > Searching the archives I found references suggesting I should create an XML
> > file (just like in asciidoc). This file should be named like the book, but
> > have an additional suffix "-docinfo.xml".
> >
> > I did so, but asciidoctor doesn't seem to embed the contents of the
> > docinfo file. Is there any additional switch/option I need to set? Here's
> > what I did to verify procedure...
> >
> > I've created a book.adoc file and added these attributes:
> >
> > ----
> > Book
> > ====
> > :doctype: book
> > :docinfo: private
> > ----
> >
> > Then I created a dook-docinfo.xml file, containing this dataset:
> >
> > ----
> > <revhistory>
> >   <revision>
> >     <revnumber>0.01</revnumber>
> >     <date>2018-11-22</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         First remark
> >     </revremark>
> >   </revision>
> >   <revision>
> >     <revnumber>0.02</revnumber>
> >     <date>2018-11-23</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         Another remark
> >     </revremark>
> >   </revision>
> > </revhistory>
> > ----
> >
> > Finally I used this command to proecess the asciidoc file and have it
> > create HTML output:
> >
> > $ asciidoctor book.adoc
> >
> > But the only file that holds the string remains book-docinfo.xml:
> >
> > $ grep PBK book*
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> >
> > Am I doing it wrong?
> >
> > Thanks,
> >
> > p@rick
> >
> > $ asciidoctor -V
> > Asciidoctor 1.5.8 [https://asciidoctor.org]
> > Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156)
> > [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
> >
> > ------------------------------
> > If you reply to this email, your message will be added to the discussion
> > below:
> >
> > http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594.html
> > To start a new topic under Asciidoctor :: Discussion, email
> > [hidden email]
> > To unsubscribe from Asciidoctor :: Discussion, click here
> > <
> > .
> > NAML
> > <
http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >
>
>
> --
> Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
>
>
> _______________________________________________
> If you reply to this email, your message will be added to the discussion below:
> http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6595.html
> To start a new topic under Asciidoctor :: Discussion, email [hidden email]
> To unsubscribe from Asciidoctor :: Discussion, visit
[*] sys4 AG
 
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
 
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
 
Reply | Threaded
Open this post in threaded view
|

Re: Creating a visible Revision History

mojavelinux
Administrator
asciidoctor allows me to use *-docinfo.html, but this will only let me add content into the head-section:

That's because this is still an open issue. See https://github.com/asciidoctor/asciidoctor/issues/1720

If there's no mechanism in asciidoctor at the moment to help me do that I will simply use a table and add that to my documents. No need to bother, then.

Asciidoctor allows every line of HTML that is generated to be customized. docinfo is just a convenience for injecting content into the output at fixed locations. If you want total control, you can pass a custom template, in this case for the document node.


Here's the precursor to a tutorial about how to use them:  https://github.com/asciidoctor/asciidoctor.org/issues/80

Cheers,

-Dan

On Sat, Nov 24, 2018 at 5:47 AM Patrick Ben Koetter [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan,

thank you for taking the time to answer my question.

I don't believe this will get me closer to my goal. What I want is *visible*
content, e.g. a table, that holds information like this:

                    Versionhistory
Release     Date        Description                 Name
0.3         28.06.2017  Dokumentreview und          PBK
                        Ergänzung für Erarbeitung
                        eines Gestaltungkatalogs.
0.2         August 2015 Added new sections with     PBK
                        cover page, automated SVG
                        and GIF conversion and
                        diagrams
0.1         August 2015 Initial version             PBK

IIRC DocBook provides this via book-revhistory.xml and – my memory may serve
me wrong – I think asciidoc (Python) was able to handle this as well.

asciidoctor allows me to use *-docinfo.html, but this will only let me add
content into the head-section:

- <base>
- <link>
- <meta>
- <noscript>
- <script>
- <style>

If there's no mechanism in asciidoctor at the moment to help me do that I will
simply use a table and add that to my documents. No need to bother, then.

Cheers,

p@rick



* mojavelinux [via Asciidoctor :: Discussion] <[hidden email]>:

>
>
> Patrick,
>
> The docinfo file you created is for DocBook output, but you are creating an
> HTML document. You either need to create a DocBook file:
>
> asciidoctor -b docbook book.adoc
>
> or you need to make a docinfo file for HTML named book-docinfo.html.
>
> Asciidoctor is simply injecting the docinfo content into the output
> document.
>
> See https://asciidoctor.org/docs/user-manual/#docinfo-file for details.
>
> Cheers,
>
> -Dan
>
> On Fri, Nov 23, 2018 at 9:44 AM Patrick Ben Koetter [via Asciidoctor ::
> Discussion] <[hidden email]> wrote:
>
> > Greetings!
> >
> > First of all thank you very much for all the great work you've put into
> > asciidoctor. I'm a long time asciidoc user and you've really taken the
> > subject a significant step further.
> >
> > I'm trying to place a visible revision history at the beginning of a book.
> > Searching the archives I found references suggesting I should create an XML
> > file (just like in asciidoc). This file should be named like the book, but
> > have an additional suffix "-docinfo.xml".
> >
> > I did so, but asciidoctor doesn't seem to embed the contents of the
> > docinfo file. Is there any additional switch/option I need to set? Here's
> > what I did to verify procedure...
> >
> > I've created a book.adoc file and added these attributes:
> >
> > ----
> > Book
> > ====
> > :doctype: book
> > :docinfo: private
> > ----
> >
> > Then I created a dook-docinfo.xml file, containing this dataset:
> >
> > ----
> > <revhistory>
> >   <revision>
> >     <revnumber>0.01</revnumber>
> >     <date>2018-11-22</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         First remark
> >     </revremark>
> >   </revision>
> >   <revision>
> >     <revnumber>0.02</revnumber>
> >     <date>2018-11-23</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         Another remark
> >     </revremark>
> >   </revision>
> > </revhistory>
> > ----
> >
> > Finally I used this command to proecess the asciidoc file and have it
> > create HTML output:
> >
> > $ asciidoctor book.adoc
> >
> > But the only file that holds the string remains book-docinfo.xml:
> >
> > $ grep PBK book*
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> >
> > Am I doing it wrong?
> >
> > Thanks,
> >
> > p@rick
> >
> > $ asciidoctor -V
> > Asciidoctor 1.5.8 [https://asciidoctor.org]
> > Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156)
> > [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
> >
> > ------------------------------
> > If you reply to this email, your message will be added to the discussion
> > below:
> >
> > http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594.html
> > To start a new topic under Asciidoctor :: Discussion, email
> > [hidden email]
> > To unsubscribe from Asciidoctor :: Discussion, click here
> > <
> > .
> > NAML
> > <
http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >
>
>
> --
> Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
>
>
> _______________________________________________
> If you reply to this email, your message will be added to the discussion below:
> http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6595.html
> To start a new topic under Asciidoctor :: Discussion, email [hidden email]
> To unsubscribe from Asciidoctor :: Discussion, visit
[*] sys4 AG
 
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
 
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
 



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6597.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Creating a visible Revision History

mojavelinux
Administrator
Another option is to just using an include directive at the top of the document that includes an AsciiDoc table that contains the revision history.

-Dan

On Sat, Nov 24, 2018 at 7:48 AM mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
asciidoctor allows me to use *-docinfo.html, but this will only let me add content into the head-section:

That's because this is still an open issue. See https://github.com/asciidoctor/asciidoctor/issues/1720

If there's no mechanism in asciidoctor at the moment to help me do that I will simply use a table and add that to my documents. No need to bother, then.

Asciidoctor allows every line of HTML that is generated to be customized. docinfo is just a convenience for injecting content into the output at fixed locations. If you want total control, you can pass a custom template, in this case for the document node.


Here's the precursor to a tutorial about how to use them:  https://github.com/asciidoctor/asciidoctor.org/issues/80

Cheers,

-Dan

On Sat, Nov 24, 2018 at 5:47 AM Patrick Ben Koetter [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan,

thank you for taking the time to answer my question.

I don't believe this will get me closer to my goal. What I want is *visible*
content, e.g. a table, that holds information like this:

                    Versionhistory
Release     Date        Description                 Name
0.3         28.06.2017  Dokumentreview und          PBK
                        Ergänzung für Erarbeitung
                        eines Gestaltungkatalogs.
0.2         August 2015 Added new sections with     PBK
                        cover page, automated SVG
                        and GIF conversion and
                        diagrams
0.1         August 2015 Initial version             PBK

IIRC DocBook provides this via book-revhistory.xml and – my memory may serve
me wrong – I think asciidoc (Python) was able to handle this as well.

asciidoctor allows me to use *-docinfo.html, but this will only let me add
content into the head-section:

- <base>
- <link>
- <meta>
- <noscript>
- <script>
- <style>

If there's no mechanism in asciidoctor at the moment to help me do that I will
simply use a table and add that to my documents. No need to bother, then.

Cheers,

p@rick



* mojavelinux [via Asciidoctor :: Discussion] <[hidden email]>:

>
>
> Patrick,
>
> The docinfo file you created is for DocBook output, but you are creating an
> HTML document. You either need to create a DocBook file:
>
> asciidoctor -b docbook book.adoc
>
> or you need to make a docinfo file for HTML named book-docinfo.html.
>
> Asciidoctor is simply injecting the docinfo content into the output
> document.
>
> See https://asciidoctor.org/docs/user-manual/#docinfo-file for details.
>
> Cheers,
>
> -Dan
>
> On Fri, Nov 23, 2018 at 9:44 AM Patrick Ben Koetter [via Asciidoctor ::
> Discussion] <[hidden email]> wrote:
>
> > Greetings!
> >
> > First of all thank you very much for all the great work you've put into
> > asciidoctor. I'm a long time asciidoc user and you've really taken the
> > subject a significant step further.
> >
> > I'm trying to place a visible revision history at the beginning of a book.
> > Searching the archives I found references suggesting I should create an XML
> > file (just like in asciidoc). This file should be named like the book, but
> > have an additional suffix "-docinfo.xml".
> >
> > I did so, but asciidoctor doesn't seem to embed the contents of the
> > docinfo file. Is there any additional switch/option I need to set? Here's
> > what I did to verify procedure...
> >
> > I've created a book.adoc file and added these attributes:
> >
> > ----
> > Book
> > ====
> > :doctype: book
> > :docinfo: private
> > ----
> >
> > Then I created a dook-docinfo.xml file, containing this dataset:
> >
> > ----
> > <revhistory>
> >   <revision>
> >     <revnumber>0.01</revnumber>
> >     <date>2018-11-22</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         First remark
> >     </revremark>
> >   </revision>
> >   <revision>
> >     <revnumber>0.02</revnumber>
> >     <date>2018-11-23</date>
> >     <authorinitials>PBK</authorinitials>
> >     <revremark>
> >         Another remark
> >     </revremark>
> >   </revision>
> > </revhistory>
> > ----
> >
> > Finally I used this command to proecess the asciidoc file and have it
> > create HTML output:
> >
> > $ asciidoctor book.adoc
> >
> > But the only file that holds the string remains book-docinfo.xml:
> >
> > $ grep PBK book*
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> > book-docinfo.xml:    <authorinitials>PBK</authorinitials>
> >
> > Am I doing it wrong?
> >
> > Thanks,
> >
> > p@rick
> >
> > $ asciidoctor -V
> > Asciidoctor 1.5.8 [https://asciidoctor.org]
> > Runtime Environment (ruby 2.5.3p105 (2018-10-18 revision 65156)
> > [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
> >
> > ------------------------------
> > If you reply to this email, your message will be added to the discussion
> > below:
> >
> > http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594.html
> > To start a new topic under Asciidoctor :: Discussion, email
> > [hidden email]
> > To unsubscribe from Asciidoctor :: Discussion, click here
> > <
> > .
> > NAML
> > <
http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >
>
>
> --
> Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
>
>
> _______________________________________________
> If you reply to this email, your message will be added to the discussion below:
> http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6595.html
> To start a new topic under Asciidoctor :: Discussion, email [hidden email]
> To unsubscribe from Asciidoctor :: Discussion, visit
[*] sys4 AG
 
https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München
 
Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein
 



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6597.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Creating-a-visible-Revision-History-tp6594p6599.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Creating a visible Revision History

wolandscat
That's what we do.

Here's an example of the source of a rev hist for one of our specs.

Here's the output.

- thomas