reorganize omdoc trunk directory structure

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 4:37pm

This ticket was triggered by an e-mail from Christoph about the lib directory. We shoud think about the overall structure of the

Wouldn't it make sense to rearrange that directory a bit? The only resource from that directory that we need here is the Makefiles, but the directory also contains other stuff (like the Emacs mode) we are not interested in. If we are more and more going to reuse the Makefiles as externals, I think it would make sense to put them into a subdirectory lib/make. BTW, why not reuse them in the "teaching" repository as well?

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 4:38pm

you are absolutely right. We should probably re-organize all of the OMDoc directory structure. BTW, lib contains a css subdir, which seems to be the "original" for css. That should also be considered in the XSLT/CSS--> jomdoc move. I am not sure where to put stuff like the emacs mode....

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 4:58pm

hmmm, let us look at the current situation: ls repos/omdoc/trunk gives

Makefile    css     dtd     lib     rnc     xsl2
bin     doc     examples    owl     thirdParty

One of my goals is to make the top-level structure less cluttered and more plausible.

I guess Makefile, and doc are standard and uncritical. The content of doc has been re-organized already, and I am happy with it.

xsl2 and css will move to JOMDoc, but will probably have to become externals somewhere, their content will be re-organized separately there.

dtd is deprecated and will be generated from the rnc}} in the future. Their content is OK. I think they should probably become subdirs under a top-level dir {{{schema. Then we can also generate a W3C XSD schema there. The only drawback is that the rnc URL becomes one step longer.

examples is important, but the content should move to TNTbase in the near future; then they will probably be restricted to the examples in the spec, so examples could move into the doc directory.

lib is the starting point of the current reorganization request, it is cluttered inside, containing things like the makefile, css, and Makefiles. To allow separate externals, this should at least be organized into separate subdirs.

bin as a subdir is standard but this one is quite cluttered inside. Some of the stuff are really tools; maybe a top-level tools directory would help.

thirdParty should really not be top-level.

owl is the home of the system ontology, this should stay on top-level, but may be renamed. Especially since the system ontology will probably be written up as OMDoc in the 1.7 timeframe.

So, these are my first thoughts, @Christoph, please coment, and then we can think up a concrete directory structure.

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 5:11pm

Replying to [comment:2 kohlhase]:

xsl2 and css will move to JOMDoc, but will probably have to become externals somewhere, their content will be re-organized separately there.

I see, that is the "css" that you mentioned. The CSS that I moved to JOMDoc was in lib/css. The top-level "css" directory doesn't contain any CSS that was used for the XHTML output generated by JOMDoc, but it contains a CSS for directly viewing OMDoc XML in the browser. Should we also move that CSS into the new place?

About xsl2: Now that we've committed to XSLT 2 as an implementation language, how about renaming this to simply "xsl"? Note that that requires adaptation of the Makefiles.

How about introducing a subdirectory style'' with externals pointing to ''css'' and ''xslt?

dtd is deprecated and will be generated from the rnc}} in the future. Their content is OK. I think they should probably become subdirs under a top-level dir {{{schema. Then we can also generate a W3C XSD schema there. The only drawback is that the rnc URL becomes one step longer. I support this. examples is important, but the content should move to TNTbase in the near future; then they will probably be restricted to the examples in the spec, so examples could move into the doc directory. Maybe we still want to keep an external pointing to the examples dir in TNTbase. lib is the starting point of the current reorganization request, it is cluttered inside, containing things like the makefile, css, and Makefiles. To allow separate externals, this should at least be organized into separate subdirs.

• css is already an external pointing to the new location of the CSS inside JOMDoc.
• javascript is marked as a TODO when the rhetorical annotations will be integrated into JOBAD (see jomdoc:ticket:99).
• I think emacs'' can be moved into ''projects
• admin'' needs to be kept somewhere, but not in ''lib. bin as a subdir is standard but this one is quite cluttered inside. Some of the stuff are really tools; maybe a top-level tools directory would help. I don't see much clutter in bin'', but on the other hand most of it is obsolete. rnv and msv should have been superseded by the integration of RELAX NG validation into JOMDoc. As JOMDoc works fine as a frontend for applying XSL transformations to OMDoc files, we can also delete the XSLT processor wrappers gestalt-wrapper and saxon. make2files is obsolete, as it was used in the pre-JOMDoc formula renderer. Not sure what ''presentationDigest is, but it looks completely obsolete to me. thirdParty should really not be top-level. If we had tools'', we could make ''thirdParty a subdirectory of that.
• jakarta-regexp: Readme written by Paul Libbrecht; what was it needed for??
• jquery: obsolete, only used by the rhetorical visualization JavaScript mentioned above, which has to move into JOBAD
• saxon: obsolete, as it's bundled with JOMDoc owl is the home of the system ontology, this should stay on top-level, but may be renamed. Especially since the system ontology will probably be written up as OMDoc in the 1.7 timeframe. So how about ontology? As with the schemas, we could then have subdirectories:
• omdoc: the master source
• owl: the OWL generated from that

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:39pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

xsl2 and css will move to JOMDoc, but will probably have to become externals somewhere, their content will be re-organized separately there.

I see, that is the "css" that you mentioned. The CSS that I moved to JOMDoc was in lib/css. The top-level "css" directory doesn't contain any CSS that was used for the XHTML output generated by JOMDoc, but it contains a CSS for directly viewing OMDoc XML in the browser. Should we also move that CSS into the new place? I think that this should be moved to the new place as well, probably in parallel to the XSLT implementation, since it constitutes an alternative output format. That being said, I think the "other" CSS should be a subdirectory of XSLT, since it only styles the result of the XSLT transformation.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:42pm

Replying to [comment:3 clange]:

About xsl2: Now that we've committed to XSLT 2 as an implementation language, how about renaming this to simply "xsl"? Note that that requires adaptation of the Makefiles. We should think about a more descriptive name for the output stream. xsl/xsl2 is just the implementation language, what we want to say is that we are creating output for the browser, maybe something like default-presentation (uaaah how ugly). But I think that xsl is the wrong level of name, do you have good ideas?

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:43pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

dtd is deprecated and will be generated from the rnc}} in the future. Their content is OK. I think they should probably become subdirs under a top-level dir {{{schema. Then we can also generate a W3C XSD schema there. The only drawback is that the rnc URL becomes one step longer. I support this. OK, let's do this; maybe make a new ticket out of this?

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:45pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

How about introducing a subdirectory style'' with externals pointing to ''css'' and ''xslt? I think that this is a good idea; only that I would probably call it pres, since it is presentation.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:46pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

examples is important, but the content should move to TNTbase in the near future; then they will probably be restricted to the examples in the spec, so examples could move into the doc directory. Maybe we still want to keep an external pointing to the examples dir in TNTbase. That is a good idea, maybe all the examples should go into TNTbase. We will need to think about this some more.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:49pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

lib is the starting point of the current reorganization request, it is cluttered inside, containing things like the makefile, css, and Makefiles. To allow separate externals, this should at least be organized into separate subdirs.

• css is already an external pointing to the new location of the CSS inside JOMDoc.
• javascript is marked as a TODO when the rhetorical annotations will be integrated into JOBAD (see jomdoc:ticket:99). OK.
• I think emacs'' can be moved into ''projects then you propose a top-level directory projects? I think that would be good, but how do projects differ from tools? Do we have both?

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:52pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

• admin'' needs to be kept somewhere, but not in ''lib. There is also an admin'' directory at top-level that comes from the way we administer the svn. I could open this up to the public and only keep the ''repos'' subdir publid. Then the content ''lib/admin could move there.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:56pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]: I don't see much clutter in bin'', but on the other hand most of it is obsolete. rnv and msv should have been superseded by the integration of RELAX NG validation into JOMDoc. As JOMDoc works fine as a frontend for applying XSL transformations to OMDoc files, we can also delete the XSLT processor wrappers gestalt-wrapper and saxon. make2files is obsolete, as it was used in the pre-JOMDoc formula renderer. Not sure what ''presentationDigest is, but it looks completely obsolete to me. let's clean this up as you propose directly, we can do this without disruption (the stuff still survives on the branches) and we get a better overview.

thirdParty should really not be top-level. If we had tools'', we could make ''thirdParty a subdirectory of that. I would probably add the content of thirdparty after cleanup, they are all tools, so it looks to me that this is in effect a rename.

• jakarta-regexp: Readme written by Paul Libbrecht; what was it needed for??
• jquery: obsolete, only used by the rhetorical visualization JavaScript mentioned above, which has to move into JOBAD
• saxon: obsolete, as it's bundled with JOMDoc we should also clean this up as you suggest.

@CHRISTOPH, can you do this directly?

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 5:57pm

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

owl is the home of the system ontology, this should stay on top-level, but may be renamed. Especially since the system ontology will probably be written up as OMDoc in the 1.7 timeframe. So how about ontology? As with the schemas, we could then have subdirectories:

• omdoc: the master source
• owl: the OWL generated from that I support this, but maybe we want to use the name 'sysonto' for that, since we do not want domain ontologies there.

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 6:23pm

Replying to [comment:4 kohlhase]:

I think that this should be moved to the new place as well, probably in parallel to the XSLT implementation, since it constitutes an alternative output format. That being said, I think the "other" CSS should be a subdirectory of XSLT, since it only styles the result of the XSLT transformation. So what structure do you suggest?

jomdoc/src/prj/style/trunk
|- xsl
|  `- css (the CSS for displaying XHTML rendered from OMDoc)
`- css (the CSS for directly viewing OMDoc in the browser)

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 6:24pm

Replying to [comment:5 kohlhase]:

We should think about a more descriptive name for the output stream. xsl/xsl2 is just the implementation language, what we want to say is that we are creating output for the browser, maybe something like default-presentation (uaaah how ugly). But I think that xsl is the wrong level of name, do you have good ideas? Why not just "presentation"?

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 6:25pm

Replying to [comment:14 clange]:

Replying to [comment:5 kohlhase]:

We should think about a more descriptive name for the output stream. xsl/xsl2 is just the implementation language, what we want to say is that we are creating output for the browser, maybe something like default-presentation (uaaah how ugly). But I think that xsl is the wrong level of name, do you have good ideas? Why not just "presentation"? Sorry, you had already said "pres"

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 6:26pm

Replying to [comment:6 kohlhase]:

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

dtd is deprecated and will be generated from the rnc}} in the future. Their content is OK. I think they should probably become subdirs under a top-level dir {{{schema. Then we can also generate a W3C XSD schema there. The only drawback is that the rnc URL becomes one step longer. I support this. OK, let's do this; maybe make a new ticket out of this?

1463

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 6:28pm

Replying to [comment:9 kohlhase]:

Replying to [comment:3 clange]:

• I think emacs'' can be moved into ''projects then you propose a top-level directory projects? I think that would be good, but how do projects differ from tools? Do we have both? Right, there is not really a difference. BTW, we also have projects as a top-level directory on the same level as trunk, maybe that also needs to be taken into account.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 6:50pm

Replying to [comment:17 clange]:

Replying to [comment:9 kohlhase]:

Replying to [comment:3 clange]:

• I think emacs'' can be moved into ''projects then you propose a top-level directory projects? I think that would be good, but how do projects differ from tools? Do we have both? Right, there is not really a difference. BTW, we also have projects as a top-level directory on the same level as trunk, maybe that also needs to be taken into account.

OK you have a point here, so I propose to add a directory tools and relegate the unfinished stuff (like the emacs mode to ../projects.

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 7:14pm

Replying to [comment:12 kohlhase]:

Replying to [comment:3 clange]:

So how about ontology? As with the schemas, we could then have subdirectories:

• omdoc: the master source
• owl: the OWL generated from that I support this, but maybe we want to use the name 'sysonto' for that, since we do not want domain ontologies there. I'm still not satisfied with the term "system ontology". I would no longer say "document ontology" either, as my current understanding of a "document ontology" is that it just captures document structures like sections, footnotes, non-semantic crossrefs etc. But on the other hand the only actual "system ontology" I'm aware of in the OMDoc context is my mathematical argumentation ontology, which actually defines a workflow of a system (i.e. the discussions in SWiM).

Maybe the generic term "ontology" cannot be mistaken that easily, as we've decided to call domain ontologies "metadata vocabularies" in the OMDoc context (as they will mainly be used for that purpose).

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 7:23pm

Replying to [comment:11 kohlhase]:

let's clean this up as you propose directly, we can do this without disruption (the stuff still survives on the branches) and we get a better overview. About bin: I had to leave rnv there, as the Makefile.test.* still reference it. Maybe you want to clean this up.

thirdParty should really not be top-level. If we had tools'', we could make ''thirdParty a subdirectory of that. I would probably add the content of thirdparty after cleanup, they are all tools, so it looks to me that this is in effect a rename. It's now been renamed but is empty. We need to decide what we want to have in there. Why not put emacs there? (See my other comment on that.)

• jquery: obsolete, only used by the rhetorical visualization JavaScript mentioned above, which has to move into JOBAD we should also clean this up as you suggest. I cleaned up everything in thirdParty. The JavaScripts that power the rhetorical visualization are now (temporarily!) in examples/varia to keep the old, existing demo self-contained, but integrating everything into JOBAD is scheduled. We (= Jana) just can't do everything at once.

[jbs1]

migrated from Trac, where originally posted by clange on 4-Mar-2009 7:34pm

Replying to [comment:18 kohlhase]:

OK you have a point here, so I propose to add a directory tools and relegate the unfinished stuff (like the emacs mode to ../projects. Is the Emacs mode really unfinished? Of course, but, I mean, does it work? If it does, and if it should be continued along with the further evolution of OMDoc, I think it should rather be in "tools". On the other hand, if it does not work and is unlikely to be resumed soon, I agree that it should move to ../projects.

What I meant by referring to ../projects is that that'' directory might also need a cleanup. I don't know much about the particular projects, but at least ''omdoc-2.0 belongs elsewhere.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 7:48pm

OK, I agree with that, but let's keep our reorganization efforts to the OMDoc trunk at the moment. I spun of issue #1464 for this.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 8:02pm

Replying to [comment:10 kohlhase]:

Replying to [comment:3 clange]:

Replying to [comment:2 kohlhase]:

• admin'' needs to be kept somewhere, but not in ''lib. There is also an admin'' directory at top-level that comes from the way we administer the svn. I could open this up to the public and only keep the ''repos'' subdir publid. Then the content ''lib/admin could move there.

I have cleaned up admin

[jbs1]

migrated from Trac, where originally posted by kohlhase on 4-Mar-2009 8:08pm

Replying to [comment:21 clange]:

Replying to [comment:18 kohlhase]:

OK you have a point here, so I propose to add a directory tools and relegate the unfinished stuff (like the emacs mode to ../projects. Is the Emacs mode really unfinished? Of course, but, I mean, does it work? If it does, and if it should be continued along with the further evolution of OMDoc, I think it should rather be in "tools". On the other hand, if it does not work and is unlikely to be resumed soon, I agree that it should move to ../projects.

What I meant by referring to ../projects is that that'' directory might also need a cleanup. I don't know much about the particular projects, but at least ''omdoc-2.0 belongs elsewhere.

unfortunatel, it is orphaned at the moment and does not quite work. So I am putting it into projects for the moment.

[jbs1]

migrated from Trac, where originally posted by kohlhase on 19-Jul-2009 9:03am

I think that this reorganization is done (for the moment). I see no pending parts here. Closing this ticket.