search

fesch / Structorizer.Desktop

Structorizer is a little tool which you can use to create Nassi-Schneiderman Diagrams (NSD).
https://structorizer.fisch.lu
GNU General Public License v3.0
65 stars 20 forks source link

Request: Structorizer User Guide #235

Closed mtstorm closed 4 years ago

mtstorm commented 8 years ago

We wish to use the application in one of our courses. Can we integrate the guide in the course? We use docbook and we did not find the documentation in git. If you wish we can help to do the conversion :-)

codemanyak commented 8 years ago

What kind of conversion do you ask for? You know that you can download a PDF version of the User Guide from the Structorizer home page? Moreover, selecting the menu item Help -> User Guide or pressing button F1 in Structorizer itself opens the online user guide in the browser, at least in the latest version (3.24-14).

codemanyak commented 8 years ago

Oh, sorry, you already wrote that you want to integrate it in DocBook format. I overlooked it. Still, the question remains what DocBook version (5.0?). Currently, the user guide is authored in a proprietary CMS based on HTML. So it would have to be rewritten (at least partially) unless tools like DocParse, herold, or html2db (?) might be tried for an automatic conversion from HTML to DocBook. There is a hint to an xlst solution in StackOverflow. I also found the following advice in the oXygen XML forum:

You can copy and paste from a browser to a DocBook 5 file and if that is open in the Author editing mode then oXygen will trigger its smart paste conversion to DocBook5

We haven't checked any of these possibilities by now.

mtstorm commented 8 years ago

Yes I know, but you can not integrate it in other documentation. We use docbook for this, and that can generate documents to any kind of format, like pdf, epub, html eg. We can help to do this. We have it up and running using Saxon and ANT.

codemanyak commented 8 years ago

Well, from my point of view, your offered help will certainly be very welcome. I can't imagine Bob objecting ;-) We both just returned from vacation, and he will certainly have found a similarly high pile of work to be done ASAP, too. As the originator of the CMS the User Guide is being maintained in, he had made a noticable effort to establish a way to derive a PDF document. I'm sure he will appreciate your experience in the development of a conversion to DocBook. A different decision will then be whether to continue editing the User Guide in the CMS and regularly to derive the DocBook version by script (in order to allow various further conversions) or to switch to maintaining the User Guide in DocBook primarily (where at least I have no experience).

reks99 commented 8 years ago

Hi,

I find it a good idea to have the documentation in docBook, so everybody who wants can translate or enhance it by itself - if wanted.

Just my 2 ct.

Fine regards Rolf

codemanyak commented 8 years ago

@reks99 I think we understood that. Bob's looking for solutions.

codemanyak commented 7 years ago

@mtstorm Hi, are you able to convert the single-HTML version of the User Guide as offered by the Structorizer homepage to DocBook (I mean, on a regular basis) or do you still need or expect further support?

mtstorm commented 7 years ago

Sorry for the delay. I can start converting the existing documents to docbook format version 5. I will start it this weekend. It will take some time for me, but I will keep you posted.

GitMensch commented 7 years ago

@codemanyak If I understood this correctly it is a one time conversion to DocBook (at least partly a manual process) and then place the DocBook in the source tree and make changes there + easily generate a HTML version from the file when preparing a release - no further documentation would be done in the HTML file.

mtstorm commented 7 years ago

Yes that is correct.

fesch commented 7 years ago

Just to notice: this would kill the online help, wouldn't it?

GitMensch commented 7 years ago

No, you just need a build-step in your IDE or in the make-scripts and the online help would be regenerated from the DocBook.

fesch commented 7 years ago

Cool, didn't know that DocBook could generate SQL code :-D

GitMensch commented 7 years ago

You've stored the content of http://help.structorizer.fisch.lu/index.php in a database? I think this shouldn't be necessary any more when the conversion to DocBook is finished. GCC generates it documentation from texinfo files to PDF, HTML single page and HTML multi page - I think DocBook should be able to do the same conversions. If I remember correctly the images are stored external, therefore the final source wouldn't be stored in the database but in a subfolder at github.

Before this big work is started can I suggest to think about using reStructuredText instead of the the Docbook format? It can be converted to many output formats, too and with Read the docs there is a nice online frontend for browsing the docs which are stored at the project's GitHub repository under a doc subdirectory. Therefore people can easily (if they know how to use GitHub) do a change and pull Request (Read the Docs includes a "Edit on GitHub" button). For an example see here, browse the page and click the "Edit" button in the upper right corner.

fesch commented 7 years ago

http://help.structorizer.fisch.lu/index.php is the front end. All content, except for the images, is stored in the database and edited via CMS.

I have no need to change anything. What is in place, is fine for me.

GitMensch commented 7 years ago

I have no need to change anything. What is in place, is fine for me.

The nice thing if it would be changed to RST:

You can still use the old frontend and/or (maybe additional for versions other than the latest release) something like Read the Docs,

Please give this a thought - the conversion isn't worth the work if you won't do the changes in-tree later.

GitMensch commented 6 years ago

I've just checked the current user guide. It is just marvelous!

But still I'd like to be able to provide PR for it, which would only be possible if the sources are kept 100% in Git instead of a CMS.

Re-Reading this topic @fesch and @codemanyak seems to have different views about the "import once and provide export option [done by @mtstorm], only work on the repo, export from the repo on (sub-)releases".

Am I right that this part is already rejected? I don't think the export to PDF would be that beautiful as the current version is, but @mtstorm can likely say something about this. The biggest benefit would still be that people can easily translate the manual and the translated versions could be integrated in the repo, too...

@fesch If you reject the move from CMS to "different", does the used CMS supports staging and if yes, would you add me to the editor list with stage-only rights allowing to suggest minor edits directly?

fesch commented 6 years ago

No, the CMS has no staging. All changes applied are immediately online. But I can add you as editor if you want to.

I have no problem with the fact that somebody wants to move the content of the CMS to something different, but I clearly want to announce that this person will not be me and that whoever will do this job has to provide a new PDF on each sub-version.

I don't want to see forks on the user guide, so either everything is moved or nothing. For me, this will clearly be binary ;-)

codemanyak commented 6 years ago

@GitMensch Just some remarks from my part without ambitions to give a comprehensive evaluation of your suggestions.

The biggest benefit would still be that people can easily translate the manual and the translated versions could be integrated in the repo, too...

I think this benefit might be limited, as I have my reservations about automatic translation in the first place and about the future maintenance of linguistically updated translations in combination with added or modified master content.

manual is easily versioned and tagged along with the version, people always get the "correct" version - especially important is "master" and "last release" of course.

Usually, the user guide updating is evolutionary i.e. the guide specifies what features are new (from which version on) and which ones are deprecated. The version references vanish over the time, of course, when the current version can be regarded as sufficiently spread. But it also tries to explain old stuff in a better way. From my point of view it makes absolutely no sense to read an obsolete user guide when working with an obsolete version of Structorizer. And though I try my best to have all relevant news in the user guide when the next Structorizer version is due, I cannot guarantee that. So, updating the user guide is a somewhat gliding process, even between the versions.

Just saw @fesch answering...

I don't want to see forks on the user guide, so either everything is moved or nothing. For me, this will clearly be binary ;-)

I absolutely agree.

I clearly want to announce that this person will not be me and that whoever will do this job has to provide a new PDF on each sub-version.

Having just checked how many competetive document markup languages and tools there are, I'm absolutely sure that whatever one might fancy here will annoy many others. End users will usually by fine with a PDF and/or Html version and won't give a fart by means of which technology it was produced as far as it is instructive and up to date. I'm fine with Bob's CMS and don't have the least ambitions to rewrite all the stuff in this or hat cryptic markup language, either.

GitMensch commented 6 years ago

@mtstorm So the next step is all to you. Do you want to invest the effort to:

?

Otherwise we should close this issue.

@fesch Yes, please add me to the CMS and point me to some basic instructions.

fesch commented 6 years ago

@GitMensch : May I get your email-address please?

codemanyak commented 4 years ago

I think we may close this issue now. The initiator seems to have lost interest.