Asciidoctor :: Discussion

revhistory

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

9 messages Options

metro

Aug 04, 2014; 9:59pm

revhistory

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
--

LightGuardjp

Aug 04, 2014; 10:02pm

Re: revhistory

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

Jason Porter
http://en.gravatar.com/lightguardjp

metro

Aug 04, 2014; 10:32pm

Re: revhistory

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
--

LightGuardjp

Aug 04, 2014; 10:47pm

Re: revhistory

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

... [show rest of quote]

Jason Porter
http://en.gravatar.com/lightguardjp

metro

Aug 05, 2014; 6:38pm

Re: revhistory

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

MT
--

LightGuardjp

Aug 05, 2014; 9:08pm

Re: revhistory

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

mojavelinux

Sep 15, 2014; 7:56am

Re: revhistory

Administrator

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

https://github.com/asciidoctor/asciidoctor-extensions-lab

-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

... [show rest of quote]

Dan Allen | http://google.com/profiles/dan.j.allen

mojavelinux

Sep 15, 2014; 8:01am

Re: revhistory

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

Dan Allen | http://google.com/profiles/dan.j.allen

wolandscat

Jun 24, 2015; 6:14pm

Re: revhistory

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