Released DtdAnalyzer version 0.1

[Maloney, Christopher (NIH/NLM/NCBI) [C]]

Hi, guys,

I'm happy to announce the release of version 0.1 of the DtdAnalyzer!

I wrote up a release procedure, here: https://github.com/NCBITools/DtdAnalyzer/wiki/Release-procedure (which I shamelessly copied and hacked from the d2rq project) and then went through the steps to produce:
  * Downloads of version 0.1, in zip and tar.gz formats:
    https://github.com/NCBITools/DtdAnalyzer/downloads
  * Tag "v0.1", which is a snapshot of the repository at that state:
    https://github.com/NCBITools/DtdAnalyzer/tags
  * Release notes (which don't contain much info, yet):
    https://github.com/NCBITools/DtdAnalyzer/blob/8de7f04955251194940d5ceec18907b3026fd057/ReleaseNotes.md

If you download the zip file and unzip it on your machine (Windows or Unix), you should be able to run it right out of the box.  If you want Markdown support for comments, though, you'll still, of course, have to install pandoc and put it in your PATH.

By "out of the box", I mean, you shouldn't have to do any special setup of environment variables or anything else.  Please try this and let me know if it works for you or not:

  * Download the zip file from here:  https://github.com/downloads/NCBITools/DtdAnalyzer/DtdAnalyzer-0.1.zip

  * Unzip it

  * Open a command or shell window, and then enter the following command.  You should be able to execute it from any directory, as long as the 'path' portion correctly points to the root directory where you unzipped the stuff.  Also, take out the newlines, and enter it all on one line:
      <path>dtddocumentor –system http://jats.nlm.nih.gov/archiving/1.0/JATS-archivearticle1.dtd --exclude mml: --exclude-except mml:math
    It should run for a little while and then announce that it's done, and the documentation is in the doc subdirectory.  Open the index.html file there in a browser and check that it looks okay.

Both the 'dtdanalyzer' and 'dtddocumentor' tools should behave identically on Windows and Unix systems.  Just use the --help option to get the full list of command-line arguments for either one.  The dtddocumentor is especially flexible, thanks to Audrey’s excellent stylesheet.  You can exclude elements that based on a set of root nodes, exclude them by name, skin the documentation with custom css and js, etc.

Unfortunately, I didn't spend the time to update the README file, so it is out of date.  I hope to spend a little bit of time on that, and putting more documentation onto the GitHub wiki, before the conference, but we'll see how that goes.  Any help in that area, of course, would be great!

 

Any feedback on this release procedure, or anything else, is of course also welcome.

Cheers!

 

Chris Maloney

NIH/NLM/NCBI (Contractor)

Building 45, 5AN.24D-22

301-594-2842

 

[Demian Hess]

Distribution doesn't include the binaries and the instructions don't say to build. Not a problem for me, since I knew to look for class files. 

I built in Eclipse, then edited dtdanalyzer.bat file to look inside bin rather than build subfolder, and everything seems to work just fine.

 

--
You received this message because you are subscribed to the Google Groups "DtdAnalyzer" group.
To post to this group, send email to dtdan...@googlegroups.com.
To unsubscribe from this group, send email to dtdanalyzer...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/dtdanalyzer?hl=en.

--
Demian Hess

Avalon Consulting, LLC
527 Maple Avenue East, Suite 200, Vienna, VA 22180

Mobile: 301-943-8307
Fax: 845-367-5496
he...@avalonconsult.com

[Chris Maloney]

Hi, Demian,

Did you try it first without building? I doesn't include the .class
files, but it does include lib/DtdAnalyzer-0.1.jar, which has
everything. The batch file picks that up and puts it into the
classpath along with everything else in the lib directory, so it
should have worked.

I just tried it from the .tar.gz file, and it worked fine for me
again, on both Windows and Unix. In the process, I did notice that
somehow Github was claiming the .zip file didn't exist (even though it
lists it and provides a link) so I deleted it, re-uploaded it, and
just tested it again from scratch, and it all worked. (It even works
without a hitch in cygwin, which I didn't expect).

Demian, I'm very concerned that you didn't succeed in just running it
out of the box -- can you help to pinpoint the problem? Also, do you
think it would be better if the main DtdAnalyzer-1.0.jar file was in
the main directory, instead of in lib?

Chris

[Demian Hess]

I see: the zip distribution does not include lib/DtdAnalyzer-0.1.jar.

However, it IS inside the tar!

I dropped the jar into lib and deleted my class files and all worked just fine! So just but the jar in the zip distribution and all will be well.

[Dave Pawson]

On 13 October 2012 22:49, Chris Maloney <vold...@gmail.com> wrote:
> Hi, Demian,
>
> Did you try it first without building? I doesn't include the .class
> files, but it does include lib/DtdAnalyzer-0.1.jar, which has
> everything. The batch file picks that up and puts it into the
> classpath along with everything else in the lib directory, so it
> should have worked.

Not wishing to offend Demian, but should the documentation
be explicit in saying how to run it from the command line
Linux and DOS

bug though?
dtdanalyser.bat
set CP="%DTDANALYZER_HOME%\build"
there is no build directory?

>
> I just tried it from the .tar.gz file, and it worked fine for me
> again, on both Windows and Unix. In the process, I did notice that
> somehow Github was claiming the .zip file didn't exist (even though it
> lists it and provides a link) so I deleted it, re-uploaded it, and
> just tested it again from scratch, and it all worked. (It even works
> without a hitch in cygwin, which I didn't expect).

$ ls lib
commons-cli-1.2.jar resolver.jar xercesImpl.jar
commons-io-2.4.jar saxon9he.jar xml-apis.jar

Err. Where is the main jar file? Not in the installation directory,
not in the lib directory?

>
> Demian, I'm very concerned that you didn't succeed in just running it
> out of the box -- can you help to pinpoint the problem?

so it's 'me too'? Sorry.

I'll write the bash script.


regards



--
Dave Pawson
XSLT XSL-FO FAQ.
Docbook FAQ.
http://www.dpawson.co.uk

[Dave Pawson]

On 13 October 2012 23:27, Demian Hess <he...@avalonconsult.com> wrote:
> I see: the zip distribution does not include lib/DtdAnalyzer-0.1.jar.
>
> However, it IS inside the tar!

Ah. You beat me to it Demian.

[Chris Maloney]

Hi, guys,

Demian wrote:
> I see: the zip distribution does not include lib/DtdAnalyzer-0.1.jar.

I've been scratching my head about this since yesterday, and after
Dave's messages, I think I know what must have happened. Did you guys
get the zip file by using the big "Zip" button on the front of the
GitHub page? If so, then that would explain it. The
DtdAnalyzer-1.0.zip file that you get from the downloads page is the
complete released package. The Zip button just gives you a zipped-up
version of the latest of everything from the repository. They are not
the same at all. I've checked several times, and the .zip file on the
downloads page has identical contents to the .tar.gz.

Please let me know if that is or isn't the case. I added a big note
to the README file assuming it was, and hopefully others won't have
the same problem.

More comments below.

On Sun, Oct 14, 2012 at 3:07 AM, Dave Pawson <dave....@gmail.com> wrote:
>
> On 13 October 2012 22:49, Chris Maloney <vold...@gmail.com> wrote:
> > Hi, Demian,
> >
> > Did you try it first without building? I doesn't include the .class
> > files, but it does include lib/DtdAnalyzer-0.1.jar, which has
> > everything. The batch file picks that up and puts it into the
> > classpath along with everything else in the lib directory, so it
> > should have worked.
>
> Not wishing to offend Demian, but should the documentation
> be explicit in saying how to run it from the command line
> Linux and DOS

I updated the README file with explicit instructions for both Windows
and Unix. Let me know if you have any suggestions for improving it
(or just go ahead and amend it).

>
> bug though?
> dtdanalyser.bat
> set CP="%DTDANALYZER_HOME%\build"
> there is no build directory?

The same batch / shell script is used for developers, and so it puts
the build directory at the front of the CP, so it overrides the .jar.
It shouldn't cause any problem if the build directory doesn't exist,
should it?

> > I just tried it from the .tar.gz file, and it worked fine for me
> > again, on both Windows and Unix. In the process, I did notice that
> > somehow Github was claiming the .zip file didn't exist (even though it
> > lists it and provides a link) so I deleted it, re-uploaded it, and
> > just tested it again from scratch, and it all worked. (It even works
> > without a hitch in cygwin, which I didn't expect).
>
> $ ls lib
> commons-cli-1.2.jar resolver.jar xercesImpl.jar
> commons-io-2.4.jar saxon9he.jar xml-apis.jar

This leads me to believe you must have used the Zip button. Could you
check to see if you have a doc directory? If not, then I think, you
definitely did not get this from the downloads page.

> ...

>
> I'll write the bash script.

Bash scripts are both done -- see dtdanalyzer and dtddocumentor in the
main directory. Let me know if you try them and have any problems.

Just another note -- I stole this whole setup and deployment
architecture (including the scripts) from the
http://github.com/d2rq/d2rq project. I am a Java novice, but that
project seems pretty mature and sophisticated. I've always been
frustrated by Java apps and how hard they are to deploy and use, and
this is as clean as anything I've ever seen for Java. But, again, I'm
open to suggestions!

Thanks for trying these out and helping with this. I think, most of
our users will not be Java programmers (maybe not programmers at all)
so I think it's important that it be very simple to setup and use.

Cheers!
Chris

>
>
> regards
>
>
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> Docbook FAQ.
> http://www.dpawson.co.uk
>

[Dave Pawson]

On 14 October 2012 15:13, Chris Maloney <vold...@gmail.com> wrote:
> Hi, guys,
>
> Demian wrote:
>> I see: the zip distribution does not include lib/DtdAnalyzer-0.1.jar.
>
> I've been scratching my head about this since yesterday, and after
> Dave's messages, I think I know what must have happened. Did you guys
> get the zip file by using the big "Zip" button on the front of the
> GitHub page? If so, then that would explain it. The
> DtdAnalyzer-1.0.zip file that you get from the downloads page is the
> complete released package. The Zip button just gives you a zipped-up
> version of the latest of everything from the repository. They are not
> the same at all. I've checked several times, and the .zip file on the
> downloads page has identical contents to the .tar.gz.
>
> Please let me know if that is or isn't the case. I added a big note
> to the README file assuming it was, and hopefully others won't have
> the same problem.

Is it time to prepare a distro build separate from a dev build?
Basically a user doesn't want any of this hassle?

>
> More comments below.
>
> On Sun, Oct 14, 2012 at 3:07 AM, Dave Pawson <dave....@gmail.com> wrote:
>>
>> On 13 October 2012 22:49, Chris Maloney <vold...@gmail.com> wrote:
>> > Hi, Demian,
>> >
>> > Did you try it first without building? I doesn't include the .class
>> > files, but it does include lib/DtdAnalyzer-0.1.jar, which has
>> > everything. The batch file picks that up and puts it into the
>> > classpath along with everything else in the lib directory, so it
>> > should have worked.
>>
>> Not wishing to offend Demian, but should the documentation
>> be explicit in saying how to run it from the command line
>> Linux and DOS
>
> I updated the README file with explicit instructions for both Windows
> and Unix. Let me know if you have any suggestions for improving it
> (or just go ahead and amend it).
>
>>
>> bug though?
>> dtdanalyser.bat
>> set CP="%DTDANALYZER_HOME%\build"
>> there is no build directory?
>
> The same batch / shell script is used for developers, and so it puts
> the build directory at the front of the CP, so it overrides the .jar.
> It shouldn't cause any problem if the build directory doesn't exist,
> should it?

It's an unnecessary niggle for a user?

>> $ ls lib
>> commons-cli-1.2.jar resolver.jar xercesImpl.jar
>> commons-io-2.4.jar saxon9he.jar xml-apis.jar
>
> This leads me to believe you must have used the Zip button. Could you
> check to see if you have a doc directory? If not, then I think, you
> definitely did not get this from the downloads page.

Quite likely and yes, I have the doc directory, lots of pe-*.html files?

>
>> ...
>>
>> I'll write the bash script.
>
> Bash scripts are both done -- see dtdanalyzer and dtddocumentor in the
> main directory. Let me know if you try them and have any problems.

I missed them since they were not execute enabled, nor ending in .sh.
My fault.

>
> Just another note -- I stole this whole setup and deployment
> architecture (including the scripts) from the
> http://github.com/d2rq/d2rq project. I am a Java novice, but that
> project seems pretty mature and sophisticated. I've always been
> frustrated by Java apps and how hard they are to deploy and use, and
> this is as clean as anything I've ever seen for Java. But, again, I'm
> open to suggestions!

Your choice, I tested the one I wrote. Just need to provide the
install directory as a shell variable.

>
> Thanks for trying these out and helping with this. I think, most of
> our users will not be Java programmers (maybe not programmers at all)
> so I think it's important that it be very simple to setup and use.

Yes, agreed, hence my suggestion to make the main distro
for the user, on the assumption that they won't use the make file
nor need any test information?

Might be nice to have the xml to html build described, so
that they don't get an xml file with no indent (daunting?)

btw, running on docbook with lots of root element choices
the 'window' in the html is tiny?

Fine thereafter.
Quite a stress test that and it worked nicely.

[Chris Maloney]

Hi, Dave,

The download files DtdAnalyzer-1.0.* are intended to be distro builds,
and not dev builds.

I just realized there's yet another possibility of confusion -- I
hadn't noticed the bit "Download as zip" and "Download as tar.gz"
buttons on the downloads page itself. These, also, just download the
latest snapshot of the repository, not the user distribution packages.
This is very confusing, but I checked, and I don't think it's
possible to get rid of these buttons.

So I just rewrote the README file again, and this time, put explicit
links to the distribution files there. That is the best we can do, I
think.

I think, a lot of your suggestions below still stem from the fact that
you were using the sources, and not these pre-built packages.

If you have time and patience, could you start from scratch, and step
through the "Quick start" steps outlined on the main github page, and
let me know how that goes?

I wrote a couple more responses to your email below.


On Sun, Oct 14, 2012 at 10:31 AM, Dave Pawson <dave....@gmail.com> wrote:
>....

> Is it time to prepare a distro build separate from a dev build?
> Basically a user doesn't want any of this hassle?

As I mentioned, this DtdAnalyzer-1.0 is supposed to be a distro build.


> ...

>>
>> The same batch / shell script is used for developers, and so it puts
>> the build directory at the front of the CP, so it overrides the .jar.
>> It shouldn't cause any problem if the build directory doesn't exist,
>> should it?
>
> It's an unnecessary niggle for a user?

Well, a user should never look inside that script, so they won't know
about it. Plus, now, I've added a lot of comments to it, so if
somebody does want to roll-their-own, the comments will hopefully give
them a lot of useful info.

>>> $ ls lib
>>> commons-cli-1.2.jar resolver.jar xercesImpl.jar
>>> commons-io-2.4.jar saxon9he.jar xml-apis.jar
>>
>> This leads me to believe you must have used the Zip button. Could you
>> check to see if you have a doc directory? If not, then I think, you
>> definitely did not get this from the downloads page.
>
> Quite likely and yes, I have the doc directory, lots of pe-*.html files?

Ah! That's an artifact of your running the dtddocumentor, then. The
'doc' directory of the distro package should only contain one
'javadoc' subdirectory. So I'm still pretty sure you just have the
sources, and not the distribution package.


> ...

>> Bash scripts are both done -- see dtdanalyzer and dtddocumentor in the
>> main directory. Let me know if you try them and have any problems.
>
> I missed them since they were not execute enabled, nor ending in .sh.
> My fault.

They should be execute-enabled now, when you unzip the distro package.

>>
>> Just another note -- I stole this whole setup and deployment
>> architecture (including the scripts) from the
>> http://github.com/d2rq/d2rq project. I am a Java novice, but that
>> project seems pretty mature and sophisticated. I've always been
>> frustrated by Java apps and how hard they are to deploy and use, and
>> this is as clean as anything I've ever seen for Java. But, again, I'm
>> open to suggestions!
>
> Your choice, I tested the one I wrote. Just need to provide the
> install directory as a shell variable.

I like these from d2rq, because you just need to put the path to the
scripts into PATH, and no extra environment variables.

>> Thanks for trying these out and helping with this. I think, most of
>> our users will not be Java programmers (maybe not programmers at all)
>> so I think it's important that it be very simple to setup and use.
>
>
> Yes, agreed, hence my suggestion to make the main distro
> for the user, on the assumption that they won't use the make file
> nor need any test information?
>
> Might be nice to have the xml to html build described, so
> that they don't get an xml file with no indent (daunting?)

I assume you mean producing the HTML documentation? There's a step
for that now in the README.

>
> btw, running on docbook with lots of root element choices
> the 'window' in the html is tiny?

Maybe you didn't get the css and js files copied into the
documentation product directory? Not sure what you mean, here. You
might check to see if you have dtddoc.css and expand.js there. If
not, try again using the steps from the "quick start". They should
get copied in.

>
> Fine thereafter.
> Quite a stress test that and it worked nicely.

Thanks again!!

Chris

[Dave Pawson]

On 14 October 2012 17:52, Chris Maloney <vold...@gmail.com> wrote:
> Hi, Dave,
>
> The download files DtdAnalyzer-1.0.* are intended to be distro builds,
> and not dev builds.
>
> I just realized there's yet another possibility of confusion -- I
> hadn't noticed the bit "Download as zip" and "Download as tar.gz"
> buttons on the downloads page itself. These, also, just download the
> latest snapshot of the repository, not the user distribution packages.
> This is very confusing, but I checked, and I don't think it's
> possible to get rid of these buttons.

Is it not possible to rename them?
Very confusing, I thought they would be the same as the lower link?

>
> So I just rewrote the README file again, and this time, put explicit
> links to the distribution files there. That is the best we can do, I
> think.

Bit late when I've downloaded one or the other?
If you can't modify the page, how about making the snapshot
the same as the one you want? Is that possible?

>
> I think, a lot of your suggestions below still stem from the fact that
> you were using the sources, and not these pre-built packages.

Which seems silly really. Have a word with the hosts?

>
> If you have time and patience, could you start from scratch, and step
> through the "Quick start" steps outlined on the main github page, and
> let me know how that goes?

I'll do that today.

>
> I wrote a couple more responses to your email below.
>
>
> On Sun, Oct 14, 2012 at 10:31 AM, Dave Pawson <dave....@gmail.com> wrote:
>>....
>> Is it time to prepare a distro build separate from a dev build?
>> Basically a user doesn't want any of this hassle?
>
> As I mentioned, this DtdAnalyzer-1.0 is supposed to be a distro build.
>
>
>> ...
>>>
>>> The same batch / shell script is used for developers, and so it puts
>>> the build directory at the front of the CP, so it overrides the .jar.
>>> It shouldn't cause any problem if the build directory doesn't exist,
>>> should it?
>>
>> It's an unnecessary niggle for a user?
>
> Well, a user should never look inside that script, so they won't know
> about it. Plus, now, I've added a lot of comments to it, so if
> somebody does want to roll-their-own, the comments will hopefully give
> them a lot of useful info.

They will if they don't run from the installation directory? Or just delete
the entire directory?

>
>
>>>> $ ls lib
>>>> commons-cli-1.2.jar resolver.jar xercesImpl.jar
>>>> commons-io-2.4.jar saxon9he.jar xml-apis.jar
>>>
>>> This leads me to believe you must have used the Zip button. Could you
>>> check to see if you have a doc directory? If not, then I think, you
>>> definitely did not get this from the downloads page.
>>
>> Quite likely and yes, I have the doc directory, lots of pe-*.html files?
>
> Ah! That's an artifact of your running the dtddocumentor, then. The
> 'doc' directory of the distro package should only contain one
> 'javadoc' subdirectory. So I'm still pretty sure you just have the
> sources, and not the distribution package.

And yet looking at the github page, they would seem to be the same
(without either knowing, or studying .... or something. Is there anything
that says they are different?)

What assumptions are you making? That people run this to generate
quite unreadable XML? Isn't it more likely that they will be wanting
HTML? If the former, please add the <xsl:output indent='yes' /> to
the stylesheet.

>
>
>>
>> btw, running on docbook with lots of root element choices
>> the 'window' in the html is tiny?
>
> Maybe you didn't get the css and js files copied into the
> documentation product directory?

Was I asked to? Should it be expected of the user?
Of the package builder? Not sure what is normal.
I took the html to be complete, not having any reason
to believe otherwise?

Not sure what you mean, here. You
> might check to see if you have dtddoc.css and expand.js there. If
> not, try again using the steps from the "quick start". They should
> get copied in.

No css in the doc directory. ...

[Dave Pawson]

On 14 October 2012 17:52, Chris Maloney <vold...@gmail.com> wrote:

> If you have time and patience, could you start from scratch, and step
> through the "Quick start" steps outlined on the main github page, and
> let me know how that goes?

Which Quick start?
https://github.com/NCBITools/DtdAnalyzer No quick start there?

==================
Without reading much.. (my normal mode with new software)

Downloaded the 'package' DtdAnalyzer-0.1.zip

1. the README is .md ????? should be .txt since it is plain text
(assumes I have never heard of markdown)
2. Contains a makefile? Why?
3. The requisite files are executable. My bad.

dtdtanalyzer was executable.
?? dtddocumentor. had to run it to find out what it does?

No mention of the xslt directory, or how to use it?
-dir No mention of a default (doc?) directory

Used
$ dtddocumentor -s ... dtd -dir docs worked fine.

So it would seem I can generate XML for my own use,
or go direct from DTD to html (#win in my view!)

I didn't try the 'button' downloads (which are not marked to say what
they are!!!)

HTH DaveP

[Maloney, Christopher (NIH/NLM/NCBI) [C]]

Hi, Dave,

This is very helpful, thank you. I'm actually pretty pleased with this result, if you can get this far without reading much. Here's a reply to some of your questions.

First of all, the README is used by GitHub to display the page on the project site. So in your earlier message, when you said, "Bit late ...?", I think we were not connecting -- the user doesn't have to download to see the README file, because of this GitHub feature. That said, I think I'll try to do a 0.1.1 release tonight to make sure the README in the distro is up-to-date.

> 1. the README is .md ?????

That's a convention established by GitHub. The .md extension tells their site app how to process the README for display on the front page of the project on the GitHub site. We could also include a .txt, but I'd rather not, as it would be a maintenance point (DRY). People will see this more and more often, and I think it's a nice convention, and hope that everyone will get used to it (my 2cents).

> 2. Contains a Makefile?

See here: https://github.com/NCBITools/DtdAnalyzer/wiki/Development-environment, "Building with make". I don't see this as a problem for users -- most of them won't know what most of the files are, there, I would think.

> ?? dtddocumentor. had to run it to find out what it does?

It's mentioned on the GitHub front page, right at the top.

> No mention of the xslt directory, or how to use it?

I'll update the README and the documentation to mention that the xslts are here, and give examples of how to use them. (Added a note to issue #17 - https://github.com/NCBITools/DtdAnalyzer/issues/17).

> -dir No mention of a default (doc?) directory

Fixed. Thanks.

> So it would seem I can generate XML for my own use, or go direct from DTD to html (#win in my view!)

Great!

> I didn't try the 'button' downloads (which are not marked to say what they are!!!)

Right! You shouldn't use those! I agree that this is a GitHub nastiness, but I don't know what to do about it. The real problem, I think, is that this project doesn't have it's own "home page". If it did, we could shield everyday users from the development details. Maybe we can get one established on the jats.nlm.nih.gov site. I just created issue #29.

In your other email, you also mentioned adding "indent=yes". I think that's a great idea, and I'll do it tonight.

Chris Maloney
NIH/NLM/NCBI (Contractor)
Building 45, 5AN.24D-22
301-594-2842

[Dave Pawson]

On 15 October 2012 15:20, Maloney, Christopher (NIH/NLM/NCBI) [C]

<malo...@ncbi.nlm.nih.gov> wrote:
> Hi, Dave,
>
> This is very helpful, thank you. I'm actually pretty pleased with this result, if you can get this far without reading much. Here's a reply to some of your questions.
>
> First of all, the README is used by GitHub to display the page on the project site. So in your earlier message, when you said, "Bit late ...?", I think we were not connecting -- the user doesn't have to download to see the README file, because of this GitHub feature. That said, I think I'll try to do a 0.1.1 release tonight to make sure the README in the distro is up-to-date.

In which case I'd suggest the ?single? page to which users should be
linked should be made very clear... so that they get the information
immediately?
If the markdown file is used in two places, that to me is
cheapskating? A readme file is (in my limited experience) generally a
text file for widest applicability?
I wonder if I am bumping up against a general github feature, i.e.
unlike Sourceforge it is meant for devs, rather than users? I know
sourceforge can have
a general HTML page, then link to a download page? If that is the
case, perhaps consideration could be given, funds permitting, to have
both? Just a thought.

>
>> 1. the README is .md ?????
>
> That's a convention established by GitHub. The .md extension tells their site app how to process the README for display on the front page of the project on the GitHub site. We could also include a .txt, but I'd rather not, as it would be a maintenance point (DRY). People will see this more and more often, and I think it's a nice convention, and hope that everyone will get used to it (my 2cents).

OK, Lets agree to differ on that. I don't see markdown as being that
commonly understood.

>
>> 2. Contains a Makefile?
>
> See here: https://github.com/NCBITools/DtdAnalyzer/wiki/Development-environment, "Building with make". I don't see this as a problem for users -- most of them won't know what most of the files are, there, I would think.

which is why I suggest it is redundant ... if this set of files is for
an end user, not a dev (which I now being to doubt!!!)

>
>> ?? dtddocumentor. had to run it to find out what it does?
>
> It's mentioned on the GitHub front page, right at the top.

OK.... If we can define a front page.
Just used Google, which (via a redundant notice) took me to
https://github.com/NCBITools/DtdAnalyzer
is that how you define the front page?
Ah!!! RTFM Dave, I just found the quickstart... (Too far down the page
for the impatient).

>
>> No mention of the xslt directory, or how to use it?
>
> I'll update the README and the documentation to mention that the xslts are here, and give examples of how to use them. (Added a note to issue #17 - https://github.com/NCBITools/DtdAnalyzer/issues/17).
>
>> -dir No mention of a default (doc?) directory
>
> Fixed. Thanks.
>
>> So it would seem I can generate XML for my own use, or go direct from DTD to html (#win in my view!)
>
> Great!
>
>> I didn't try the 'button' downloads (which are not marked to say what they are!!!)
>
> Right! You shouldn't use those! I agree that this is a GitHub nastiness, but I don't know what to do about it. The real problem, I think, is that this project doesn't have it's own "home page". If it did, we could shield everyday users from the development details. Maybe we can get one established on the jats.nlm.nih.gov site. I just created issue #29.

+1. I'm beginning to see that now. github = devs. dtdanlyzer.org would
be an ideal 'home'.

>
> In your other email, you also mentioned adding "indent=yes". I think that's a great idea, and I'll do it tonight.

Otherwise the XML is plain scary.... but....
How about reversing it?
So that the prime output is the html
Oh, and if you want it, here is how you get the intermediate XML?
Not sure if that makes sense, but just a thought.

regards