#382 Slight improvements to Roma documentation

AMBER
closed-fixed
5
2013-05-14
2012-09-06
No

I've been using the command-line Roma a bit, and find there are some simple improvements we could do to documentation:

1. "man roma" gives s simple manual page which states clearly that it doesn't provide complete documentation. However, one useful addition would be to add that "roma --help" will give you better documentation. This would require a minor change to roma.1, if I understand correctly.

2. "roma --help" is much better, but this bit:

--localsource= # local copy of P5 sources

is not helpful. I had to hack around quite a lot before I discovered what would actually work; in my case, I had to point it at the guidelines-en.xml file in the P5/Source directory. I think fixing this would require establishing exactly which file it's best to point at for this (other suggestions have included the elusive p5subset.xml), and updating the documentation in rom2.sh (if that's the right file).

If I'm right about the changes needed, and where to change them, I'm happy to make them, but Sebastian should make sure I'm on the right track first.

Discussion

  • Martin Holmes

    Martin Holmes - 2013-05-10

    I've already added the roma --help enhancement. I'm now looking at how --localsource works, and figuring out that it's not really straightforward. In the past, I've pointed at guidelines-en.xml for this, and it's worked, but I think since we switched to XInclude instead of entities it no longer does. If I expand the guidelines-en.xml file first, and point at the expansion, then it does work. It also works of course if I point it at p5.xml or p5subset.xml in the P5 folder. However, neither of these are present in a default checkout, because they're generated by a build.

    It looks as though the standard stylesheets use p5subset.xml. When I try to run teitorelaxng (the alternative to CLI roma), pointing it at the local source directory, the build fails; if I point it at guidelines-en.xml, it also fails; but when I point it at p5subset.xml it succeeds. So it seems that, using either CLI roma or teitorelaxng, you need to build a copy of p5subset.xml yourself before you can use a local source.

    Should it be the case that if you run teitorelaxng pointing at a local source directory, if p5subset.xml is not there, it should be generated? If so, the CLI roma should presumably do the same thing.

    I've written to Sebastian for some help with this.

     
  • Martin Holmes

    Martin Holmes - 2013-05-14

    I've now updated the localsource parameter documentation. If everything builds OK on Jinks I'll close the ticket.

     
  • Martin Holmes

    Martin Holmes - 2013-05-14
    • status: open --> closed-fixed
    • Group: --> AMBER
     

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks