View Issue Details
ID | Project | Category | View Status | Date Submitted | Last Update |
---|---|---|---|---|---|
0008346 | mantisbt | documentation | public | 2007-09-10 21:11 | 2008-04-19 04:10 |
Reporter | vboctor | Assigned To | giallu | ||
Priority | normal | Severity | minor | Reproducibility | have not tried |
Status | closed | Resolution | fixed | ||
Target Version | 1.2.0a1 | Fixed in Version | 1.2.0a1 | ||
Summary | 0008346: Use DocBook for Mantis manual | ||||
Description | The aim of this work is to convert the current online manual to Docbook format and make it part of the CVS tree. This is to encourage active updates of the Docbook XML by the developers as part of new features. It will also allow for branching and tagging of documentation with the version of the code that corresponds to it. This is to solve the current issue where the latest manual is not consistent with the specific version that users are running. We can then use this Docbook to generate online as well as downloadable versions of the manual. The aim is to have the phpWebnotes feature enabled for the online version. This will require creating/tweaking a DocBook template. | ||||
Tags | No tags attached. | ||||
related to | 0007200 | closed | MartinFuchs | [de] FYI: German documentation |
related to | 0008966 | closed | dregad | Provide a way for Windows users to compile Docbook manual |
Reminder sent to: giallu, MartinFuchs Gianluca and Martin, this issue is to capture our progress relating to migrating our English / Localized documentation to Docbook. Gianluca has a version of the English manual that he was going to attempt converting to Docbook. Martin already converted some German documentation (0007200) to Docbook format. Once we do the conversion we have to do the following:
eDE is the tool that we use under Windows for compiling Docbook into output formats. |
|
I wrote shell scripts to use the eDE on Unix/Linux systems or Cygwin on Windows, so we are not constrained to use the batch files on Windows. Here is available my download archive and a setup instruction: |
|
Ok. first step (conversion) is done. Do we want to open additional child issues for subtasks or we just close this and move on? |
|
giallu, as per MartinFuchs comment, it seems that eDE is available on Linux as well. Hence, if we can modify your Docbook work to work with eDE then we will probably be able to compile it on both Linux and Windows, rather than just Linux. It may help to download his version and check the differences compared to ours. |
|
It seems to me that eDE is just a toolchain based on:
designed to provide, much like WAMP, a smooth installation of the required tools. Now, I could quite easily match the setup with Fedora packages, but I have zero experience in the XSLT customization layer. Is there anyone available with some XSLT expertise? |
|
Yes, eDE is based in FOP and Saxon. As this are Java programms, I only needed to port the Windows batch files to Unix shell scripts. I might (this weekend) have a look at your Makefiles and see if they can be adapted to eDE without big changes. The advantage of eDE is just, it provides some predefined layout format. Btw - do you already have the HTML output of your new Docbook manual somewhere in the net? |
|
@MartinFuchs, any updates? I have been working on the manual by using my Fedora system. Everything is working fine there. It is important for me to have at least 1 person in the development team that has experience with the tools we are using. This is specially important as our next step is to be able to customize the output to a layout that we like and to integrate phpWebnotes to work with the html multiple page template. On the other hand, I think it is important to provide a workable Windows solution for translators and users who may want to contribute to Mantis documentation. In order to achieve both, I am thinking of the following:
Another aspect is to understand which of the two alternatives is easier to learn and use. |
|
@Martin. No, I don't have any online version of the manual but I can send you a PDF if you like. just let me know your email address. @Victor: I still have to investigate further the XML toolchain setup ion Fedora; if successful, I'd move everything to XML so eDE can be used. I also have to note the following page that could help Windows users: About the final deployment and integration with phpwebnotes I think that, regardless the solution we come out for authoring, the fastest option is to process HTML pages output in PHP, "cut" the <body> part and include it in our pages. I think a similar strategy (look at page source) is used at zend.com for their php manual mirror. For instance examine: http://devzone.zend.com/manual/language.oop5.html to know what I mean. Lastly, about the learning curve, SGML and XML sources are mostly the same AFAIK so the difference is only in the effort required to install and configure the toolchain; eDE has clearly a bonus here |
|
I also tried to use the Cygwin's XML tools a while ago, but was not successfull. It seemed the XML catalog files are not set up correctly in the Cygwin installation packages. |
|
I've resolved this against 1.2 since we now have a Docbook manual. I will open specific bugs for the outstanding work. |
|