[Bug 12217] New: Documentation should be in XML and not SGML format

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@winehq.org ReportedBy: scott@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.

Show replies by date

wine-bugs＠winehq.org

25 Mar 25 Mar

6:07 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Scott Ritchie scott@open-vote.org changed:

What |Removed |Added ---------------------------------------------------------------------------- Target Milestone|--- |1.0.0

--- Comment #1 from Scott Ritchie scott@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.

wine-bugs＠winehq.org

27 Mar 27 Mar

3:03 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Dan Kegel dank@kegel.com changed:

--- Comment #2 from Dan Kegel dank@kegel.com 2008-03-26 22:03:29 --- Let's think about it a bit first...

wine-bugs＠winehq.org

28 Mar 28 Mar

5:52 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #3 from Juan Lang juan_lang@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?

wine-bugs＠winehq.org

29 Mar 29 Mar

12:49 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #4 from Scott Ritchie scott@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

wine-bugs＠winehq.org

23 Oct 23 Oct

8:37 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Austin English austinenglish@gmail.com changed:

What |Removed |Added ---------------------------------------------------------------------------- CC| |austinenglish@gmail.com

wine-bugs＠winehq.org

27 Apr 27 Apr

1:44 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Austin English austinenglish@gmail.com changed:

What |Removed |Added ---------------------------------------------------------------------------- Keywords| |download, source

--- Comment #5 from Austin English austinenglish@gmail.com 2009-04-26 20:44:24 --- Still present.

wine-bugs＠winehq.org

5 Jun 5 Jun

10:56 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #6 from Stefan Stranz sfs1988@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.

wine-bugs＠winehq.org

6 Jun 6 Jun

12:17 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #7 from Austin English austinenglish@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@winehq.org

wine-bugs＠winehq.org

22 Oct 22 Oct

11:58 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

nathan.n saturn_systems@yahoo.com changed:

What |Removed |Added ---------------------------------------------------------------------------- CC| |saturn_systems@yahoo.com

--- Comment #8 from nathan.n saturn_systems@yahoo.com 2010-10-22 18:58:06 CDT --- did this happen?

wine-bugs＠winehq.org

11:59 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #9 from Austin English austinenglish@gmail.com 2010-10-22 18:59:47 CDT --- (In reply to comment #8)

No, http://source.winehq.org/git/docs.git/?a=tree;f=en

did this happen?

wine-bugs＠winehq.org

2 Nov 2 Nov

9:53 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Jerome Leclanche adys.wh@gmail.com changed:

What |Removed |Added ---------------------------------------------------------------------------- CC| |adys.wh@gmail.com

--- Comment #10 from Jerome Leclanche adys.wh@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?

wine-bugs＠winehq.org

19 Feb 19 Feb

9:05 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #11 from Austin English austinenglish@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.

wine-bugs＠winehq.org

27 Jan 27 Jan

6:50 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #12 from Rosanne DiMesio dimesio@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.

wine-bugs＠winehq.org

7:37 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #13 from Austin English austinenglish@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.

wine-bugs＠winehq.org

8:19 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #14 from Jerome Leclanche jerome@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.

wine-bugs＠winehq.org

11:05 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #15 from Rosanne DiMesio dimesio@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.

wine-bugs＠winehq.org

11:08 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #16 from Austin English austinenglish@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.

wine-bugs＠winehq.org

28 Jan 28 Jan

4:37 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #17 from Alexandre Julliard julliard@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.

wine-bugs＠winehq.org

8 Feb 8 Feb

8:58 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

--- Comment #18 from Rosanne DiMesio dimesio@earthlink.net --- All three guides are now on the wiki:

https://wiki.winehq.org/Wine_User%27s_Guide https://wiki.winehq.org/Winelib_User%27s_Guide https://wiki.winehq.org/Wine_Developer%27s_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.

wine-bugs＠winehq.org

10 Feb 10 Feb

12:42 a.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format

Rosanne DiMesio dimesio@earthlink.net changed:

--- Comment #19 from Rosanne DiMesio dimesio@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.

wine-bugs＠winehq.org

19 Feb 19 Feb

2:57 p.m.

New subject: [Bug 12217] Documentation should be in XML and not SGML format