dtddocumentor

[Chris Maloney]

This looks great, Audrey!  Really very nice, I'm very excited.

Here's some miscellaneous feedback -- feel free to push back on any of these if you disagree.  Some of these are just my opinions, but I hope they are helpful rather than too picky...

- When zipping up a file, it's good practice to always put everything into a single subdirectory.  The reason is that somebody unzipping the file often expects this, and can get a nasty surprise when he/she unzips it into a working directory somewhere, and finds tons of files mixed in with other unrelated stuff.  I always try to make this directory the same name as the base filename of the zip file.  So, for example:

    md split-example-dtddoc

    mv <all-your-files> split-example-dtddoc

    zip -r split-example-dtddoc.zip split-example-dtddoc

- You should go ahead and add/commit the dtddocumentor xslt to the repository, in the xslt directory.  Commit early and commit often, I think, is a good idea.

- Also, if you want, you could make comments about your progress on the github issue, https://github.com/NCBITools/DtdAnalyzer/issues/4.  I've already assigned it to you.  ;-)   I'm still not sure if Sergey and others will be okay with us tracking issues on Github rather than JIRA, but personally I think it's better because it's open, and Demian and anyone else who's interested can stay up-to-date.

- This really is a great and stupendous example, and again, it really exceeds my expectations, but I'm not sure that this zip file belongs in the repository.  The thing is, that these are *product* files.  Generally speaking, the only thing that should go into the repo are source files.  You'll notice that in etc/jatscon, for example, I only added the original source code snippets, and then wrote instructions for how to produce the entities needed by the master xml, using the perl script.  I'd think for this zip file, which contains an example of the output, you could just email it to this list.

- If you want to CM the css and js, which are source files as opposed to product files, (and I notice you've made some changes to the css since you originally added it) you should add/commit them in their original text form.  Put them anywhere you want -- maybe xslt/css or etc/css, for example -- we can always move them later.  But if you put them in the zip file, then we can't get diff reports using git, since they're now part of a binary blob, so you lose a major benefit of having it in CM in the first place.

I know that's a lot of feedback, and again, I hope you don't mind.  I'll say again, I think the HTML documentation here really looks great.

Cheers!

Chris

On Fri, Sep 21, 2012 at 3:03 PM, Audrey Hamelers <audrey....@nih.gov> wrote:

By the way, I added a title to Chris's daz output mockup, ran it through my current dtddocumentor xslt, zipped up the result and put it in https://github.com/NCBITools/DtdAnalyzer/tree/master/test/split-example

[Audrey Hamelers]

1. Oh, weird: my Mac automatically puts these files into their own subdirectory. I never realized this was an issue for other people.

4. Okay, it's fine to remove it from Github. I just wanted to show you guys where things stood.