[Bug 12217] New: Documentation should be in XML and not SGML format
http://bugs.winehq.org/show_bug.cgi?id=12217 Summary: Documentation should be in XML and not SGML format Product: Wine Version: 0.9.58. Platform: Other OS/Version: other Status: NEW Severity: enhancement Priority: P2 Component: documentation AssignedTo: wine-bugs(a)winehq.org ReportedBy: scott(a)open-vote.org We need to convert the documentation to proper XML format instead of SGML. Aside from allowing us to use modern build tools, this also allows Wine's documentation to happily sit alongside other system documentation and, for instance, be indexed by scrollkeeper. -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 Scott Ritchie <scott(a)open-vote.org> changed: What |Removed |Added ---------------------------------------------------------------------------- Target Milestone|--- |1.0.0 --- Comment #1 from Scott Ritchie <scott(a)open-vote.org> 2008-03-25 13:07:11 --- I'm going to tag this as a 1.0 bug, since we don't have a general "fix documentation" bug for this to depend on anymore. -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 Dan Kegel <dank(a)kegel.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |dank(a)kegel.com Target Milestone|1.0.0 |--- --- Comment #2 from Dan Kegel <dank(a)kegel.com> 2008-03-26 22:03:29 --- Let's think about it a bit first... -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #3 from Juan Lang <juan_lang(a)yahoo.com> 2008-03-28 12:52:27 --- I'm curious what modern build tools you mean? That's not a challenge, I'm just hoping to be enlightened. What should we be using that we can't right now? -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #4 from Scott Ritchie <scott(a)open-vote.org> 2008-03-28 19:49:15 --- Oh, just the stuff that makes man pages out of XML files is more up to date than the SMGL stuff we're using, which hasn't been updated in years -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 Austin English <austinenglish(a)gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |austinenglish(a)gmail.com -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 Austin English <austinenglish(a)gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords| |download, source --- Comment #5 from Austin English <austinenglish(a)gmail.com> 2009-04-26 20:44:24 --- Still present. -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #6 from Stefan Stranz <sfs1988(a)gmail.com> 2009-06-05 17:56:12 --- Created an attachment (id=21585) --> (http://bugs.winehq.org/attachment.cgi?id=21585) Patch to add xml documentation creation to c2man Patch adds xml doc creation to c2man.pl. I also adjusted the makefiles to add make xmlpages. I had to adjust output_api_comment in c2man to correct the xml tag generation, without the adjustments the tags are not closed correctly. Was able to run dblatex using the pdf output successfully. -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #7 from Austin English <austinenglish(a)gmail.com> 2009-06-05 19:17:19 --- (In reply to comment #6)
Created an attachment (id=21585) --> (http://bugs.winehq.org/attachment.cgi?id=21585) [details] Patch to add xml documentation creation to c2man
Patch adds xml doc creation to c2man.pl.
I also adjusted the makefiles to add make xmlpages. I had to adjust output_api_comment in c2man to correct the xml tag generation, without the adjustments the tags are not closed correctly. Was able to run dblatex using the pdf output successfully.
Please send patches to wine-patches(a)winehq.org -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 nathan.n <saturn_systems(a)yahoo.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |saturn_systems(a)yahoo.com --- Comment #8 from nathan.n <saturn_systems(a)yahoo.com> 2010-10-22 18:58:06 CDT --- did this happen? -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #9 from Austin English <austinenglish(a)gmail.com> 2010-10-22 18:59:47 CDT --- (In reply to comment #8)
did this happen?
No, http://source.winehq.org/git/docs.git/?a=tree;f=en -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
http://bugs.winehq.org/show_bug.cgi?id=12217 Jerome Leclanche <adys.wh(a)gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |adys.wh(a)gmail.com --- Comment #10 from Jerome Leclanche <adys.wh(a)gmail.com> 2011-11-02 16:53:27 CDT --- I really don't understand this bug. The doc's sgml is nearly xml compliant. If there is a reason to have xml, why have sgml at all? And if there is no reason to have xml, why bother? -- Configure bugmail: http://bugs.winehq.org/userprefs.cgi?tab=email Do not reply to this email, post in Bugzilla using the above URL to reply. ------- You are receiving this mail because: ------- You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #11 from Austin English <austinenglish(a)gmail.com> --- Still present. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #12 from Rosanne DiMesio <dimesio(a)earthlink.net> --- Why don't we simply move all the documentation to the wiki? Editing in the new wiki is limited to "Trustworthy" users, so the risk of inappropriate changes being made is low. I doubt many people really care about having all those formats available. As it is, bugs that could be fixed in under a minute in the wiki sit around unfixed for years because no one wants to have to deal with that awful format (e.g., bug 9823, bug 16301, bug 37671). -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #13 from Austin English <austinenglish(a)gmail.com> --- (In reply to Rosanne DiMesio from comment #12)
Why don't we simply move all the documentation to the wiki?
In theory, other sites/projects could make use of sgml/xml, but in practice I don't think any are (and arguably they could make use of the wiki backup files for that). There's been a low-effort push to move more stuff towards the wiki, I think the reason it hasn't happened is mostly lack of effort by someone who cares / has the knowledge to move/update the information. But yes, I think moving everything into the wiki is the right course of action. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #14 from Jerome Leclanche <jerome(a)leclan.ch> --- pandoc will let you convert the sgml documentation to mediawiki without issues. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #15 from Rosanne DiMesio <dimesio(a)earthlink.net> --- As an experiment, I've done an initial import of the Wine User Guide into the wiki. Pandoc does the heavy lifting nicely (thanks for the tip, Jerome), but the output still needs manual tweaking. Formatting and links still need more work, and I haven't updated any content yet, but it's in surprisingly good shape considering how little time it took. https://wiki.winehq.org/Wine_User_Guide The question I have at this point is: if I import all the guides to the wiki, can we get rid of the sgml versions? If the answer is no, it's not worth spending my time on. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #16 from Austin English <austinenglish(a)gmail.com> --- (In reply to Rosanne DiMesio from comment #15)
The question I have at this point is: if I import all the guides to the wiki, can we get rid of the sgml versions? If the answer is no, it's not worth spending my time on.
I don't know of anyone who would object to nuking it from orbit :) -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #17 from Alexandre Julliard <julliard(a)winehq.org> --- (In reply to Rosanne DiMesio from comment #15)
The question I have at this point is: if I import all the guides to the wiki, can we get rid of the sgml versions? If the answer is no, it's not worth spending my time on.
No objections here. Is there a good way to extract it back to xml or similar, in case someone wants to ship a copy of the docs? It's by no means a requirement, just wondering if it's feasible. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 --- Comment #18 from Rosanne DiMesio <dimesio(a)earthlink.net> --- All three guides are now on the wiki: https://wiki.winehq.org/Wine_User's_Guide https://wiki.winehq.org/Winelib_User's_Guide https://wiki.winehq.org/Wine_Developer's_Guide (that page is the table of contents; each chapter is a separate subpage) I did not port "The Wine DocBook System" section of the Developer's Guide since that is now superfluous, and I revised the first part of the "Documenting Wine" chapter to refer readers to the wiki rather than the SGML files, but other than that my focus has been on porting the existing information over and making sure the formatting looks (mostly) the same, not updating content. A daily backup of the whole wiki in XML format is available on http://dl.winehq.org/wine/, and I included that link in the "Documenting Wine" chapter of the Developer's Guide. I don't know how difficult it would be to provide an XML backup of only the guides, or whether it's worth doing that. Anyone can save the Mediawiki files and use Pandoc to convert them to XML, but I suspect they'll have to manually fix some of the markup (I know I had to going the other direction). -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 Rosanne DiMesio <dimesio(a)earthlink.net> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |RESOLVED Resolution|--- |FIXED --- Comment #19 from Rosanne DiMesio <dimesio(a)earthlink.net> --- https://www.winehq.org/documentation has been updated to point to the wiki; marking fixed. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
https://bugs.winehq.org/show_bug.cgi?id=12217 Alexandre Julliard <julliard(a)winehq.org> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|RESOLVED |CLOSED --- Comment #20 from Alexandre Julliard <julliard(a)winehq.org> --- Closing bugs fixed in 1.9.4. -- Do not reply to this email, post in Bugzilla using the above URL to reply. You are receiving this mail because: You are watching all bug changes.
participants (1)
-
wine-bugs＠winehq.org