revhistory

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

revhistory

metro
I want to build a revhistory table with more complex descriptions than those allowed by revremark used by Asciidoctor.

Is there any asciidoctor native way to specify revhistory entries using revdescription or is the only way to use docinfo.xml?

Thanks,

MT
--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

LightGuardjp
Something more complex may be best done with extension. What do you have in mind?


On Mon, Aug 4, 2014 at 3:59 PM, metro [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I want to build a revhistory table with more complex descriptions than those allowed by revremark used by Asciidoctor.

Is there any asciidoctor native way to specify revhistory entries using revdescription or is the only way to use docinfo.xml?

Thanks,

MT
--



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



--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

metro
In reply to this post by metro
Something like this:
v0.2, Aug 03, 2014:
<<sectionIntroduction>>: added clarification 
<<sectionRegister>>: added register figure
v0.1, Aug 01, 2014:
<<sectionIntroduction>>, <<sectionAsciidoc>>: fixed typos
v0.0, Jul 30, 2014:
Initial release

To be rendered as:
<revhistory>
  <revision>
    <date>Aug 03, 2014</date>
    <revnumber>0.2</revnumber>
    <revdescription>
      <para><xref linkend="sectionIntroduction"/>: added clarification</para>
      <para><xref linkend="sectionRegister"/>: added register figure</para>
    </revdescription>
  </revision>
  <revision>
    <date>Aug 01, 2014</date>
    <revnumber>0.1</revnumber>
    <revdescription>
      <para><xref linkend="sectionIntroduction"/>, <xref linkend="sectionAsciidoc"/>: fixed typos</para>
    </revdescription>
  </revision>
  <revision>
    <date>Jul 30, 2014</date>
    <revnumber>0.0</revnumber>
    <revdescription><para>Initial Release</para></revdescription>
  </revision>
</revhistory>

MT
--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

LightGuardjp
Yeah, looks like a new macro (with extension) would be a fairly easy way to do that. Maybe a new block as well to kick off the revhistory section.


On Mon, Aug 4, 2014 at 4:32 PM, metro [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Something like this:
v0.2, Aug 03, 2014:
<<sectionIntroduction>>: added clarification 
<<sectionRegister>>: added register figure
v0.1, Aug 01, 2014:
<<sectionIntroduction>>, <<sectionAsciidoc>>: fixed typos
v0.0, Jul 30, 2014:
Initial release

To be rendered as:
<revhistory>
  <revision>
    <date>Aug 03, 2014</date>
    <revnumber>0.2</revnumber>
    <revdescription>
      <para><xref linkend="sectionIntroduction"/>: added clarification</para>
      <para><xref linkend="sectionRegister"/>: added register figure</para>
    </revdescription>
  </revision>
  <revision>
    <date>Aug 01, 2014</date>
    <revnumber>0.1</revnumber>
    <revdescription>
      <para><xref linkend="sectionIntroduction"/>, <xref linkend="sectionAsciidoc"/>: fixed typos</para>
    </revdescription>
  </revision>
  <revision>
    <date>Jul 30, 2014</date>
    <revnumber>0.0</revnumber>
    <revdescription><para>Initial Release</para></revdescription>
  </revision>
</revhistory>

MT
--



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



--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

metro
Thanks. Any good examples available to use as a starting point?

MT
--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

LightGuardjp
I'd have to look for them on the lists, or on github but there are many examples either on the list or in Alex's github. 

Sent from Mailbox


On Tue, Aug 5, 2014 at 12:40 PM, metro [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks. Any good examples available to use as a starting point?

MT
--



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

Reply | Threaded
Open this post in threaded view
|

Re: revhistory

mojavelinux
Administrator
Here's a bunch of extensions to use as ideas.


-Dan

On Tue, Aug 5, 2014 at 3:08 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'd have to look for them on the lists, or on github but there are many examples either on the list or in Alex's github. 

Sent from Mailbox


On Tue, Aug 5, 2014 at 12:40 PM, metro [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks. Any good examples available to use as a starting point?

MT
--



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




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



--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

mojavelinux
Administrator
In reply to this post by metro
I was just thinking about this recently and I came up with an idea that I think would greatly reduce the clutter in the document and leverage existing infrastructure to maintain the content.

Instead of keeping the revision history in the source, it makes sense to keep only the latest revision info and then rely on git to handle all the previous revisions. This would mean that you would add a revremark at the time you change the version, the commit it. To get all the previous revisions and corresponding remarks, you simply walk the git history and look for when the revision line changes. You create a catalog, then you output this perhaps to a temporary docinfo file. Then, you just convert as normal.

When you are walking the git history, you can use the Asciidctor.load API to read just the header of the document to extract the revision info.

[source,ruby]
----
doc_header = Asciidoctor.load_file 'sample.adoc', parse_header_only: true
puts doc_header.attr 'revnumber'
----

I think, by far, this is the most sustainable approach to revision history. It may take a bit of scripting to setup, but once it's in place, it should just hum.

We could work on this script in the asciidoctor-extensions-lab if you are interested to have a place to share it.

Cheers,

-Dan

On Mon, Aug 4, 2014 at 3:59 PM, metro [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I want to build a revhistory table with more complex descriptions than those allowed by revremark used by Asciidoctor.

Is there any asciidoctor native way to specify revhistory entries using revdescription or is the only way to use docinfo.xml?

Thanks,

MT
--



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



--
Reply | Threaded
Open this post in threaded view
|

Re: revhistory

wolandscat
Our ideas of 'revhistory' might differ wildly, but I'll just mention the kind of thing we use - you can see it here; adoc source is here.

This can't be built by traversing Github commits because many of the commits are much older than Github, and also a lot of Github commits don't correspond to a version (although in theory git tags could). But for this kind of document (a published standard), the revision history, even very old entries is very important.

Currently done completely manually as a table in the source.

One thing we really want that we had in FrameMaker is the ability to put an xref marker next to the revision and date in the top row, you can reference these on the front page, to show 'Current revision: <rev> ; Date: <date>', where <rev> and <date> are an actual revision and date from the revhist table.

i.e. something like:

[cols="1,6a,2,2", options="header"]
|===
|Issue|Details|Raiser|Completed

|[[rev]]2.1.14
|Refactor `ARCHETYPE` and `ARCHETYPE_TERMINOLOGY` ......
|T Beale
|[[date]]04 Jan 2015