Create account / Log in

Online Reference Manual

Topics related to the main Vassal engine.

Moderators: uckelman, Tim M

Online Reference Manual

Postby uckelman » January 23rd, 2008, 11:10 am

Thus spake "TeTeT":
rk wrote:
... It would be good to get a sense of how easy the DocBook is to edit, and
I'd like to test out the process of converting them to HTML/PDF.

I've just completed a project in docbook/XML, the Ubuntu Desktop Course (http
://launchpad.net/ubuntu-desktop-course). For any non-programmer the learning
curve is quite steep, as it requires a bit of knowledge to understand the rig
idity of the tags. Converting docbook/XML to HTML can be done quite easily wi
th xsltproc, results are ok. For conversion to pdf we used dblatex, which has
quite a few shortcomings in the layout of individual pages. It's easy to end
with graphics only pages and is very hard to force that a specific text is o
n the same page as a graphic. For printing the coursebook we've decided to go
with Formatting Objects, which requires some domain knowledge before it beco
mes useful.

Feel free to get the desktop course sources and convert them to HTML and PDF
and have a look. The official Ubuntu documentation is also written in docbook
/XML and available on launchpad.net.


I have to concur---the PDF output, while not awful, is not great either.

https://wiki.ubuntu.com/Training?action ... tudent.pdf

I think I see why you end up fighting with dblatex a bit, since you
have so many floats (the figures) with so little text between them.

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby bsmith » January 23rd, 2008, 12:18 pm

I have to concur---the PDF output, while not awful, is not great either.


I've never seen faithful conversion from one document format to another. There are always differences in font, indentation, line spacing etc.l; It never works the way you want it to, the simplest way is to write in one format, for one format.
User avatar
bsmith
Site Admin
 
Posts: 657
Joined: October 2nd, 2007, 4:47 pm

Online Reference Manual

Postby uckelman » January 23rd, 2008, 12:23 pm

Thus spake "bsmith":
I have to concur---the PDF output, while not awful, is not great either.

I've never seen faithful conversion from one document format to another. The
re are always differences in font, indentation, line spacing etc.l; It never
works the way you want it to, the simplest way is to write in one format, fo
r one format.


If I understand correctly, it's not a conversion. DocBook is a markup
language, not an output format.

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby meng » January 23rd, 2008, 2:04 pm

By "popular" request, this is the documentation I am working on. There's a lot of cut and paste from the offline module editor manual. It's missing some refinement in terms of internal linking and it has no images at present.
Attachments
vassalmodule.xml.tar.gz
preliminary only
(6.55 KiB) Downloaded 339 times
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Online Reference Manual

Postby uckelman » January 23rd, 2008, 2:17 pm

Thus spake "meng":
By "popular" request, this is the documentation I am working on. There's a lo
t of cut and paste from the offline module editor manual. It's missing some r
efinement in terms of internal linking and it has no images at present.


Oh. I was under the impression that you were working on docs for users,
not docs for module developers.

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby meng » January 23rd, 2008, 3:04 pm

Well module developers are users too. But as I see it there are (at least) 4 tasks here:
(1) deciding upon, and gaining familiarity with, a format for the documentation
(2) updating/reorganizing existing documentation
(3) generating new documentation
(4) coordination of the above efforts

So far I've concentrated on (1) and to a lesser extent (2), with a view to managing (4) if no-one else objects/volunteers. timpelican has offered to make a start on (3), which is perfect, although one could argue that that task is more a case of fleshing out the existing wiki, which falls in the realm of (2).

My thought is that once the new draft documentation is in the new format, then the tasks will be:
(5) checking for accuracy
(6) checking for consistency of format

and in regards to what rk said, the developers can do (5) and I can do (6), although (6) is somewhat a built-in feature of using DocBook (not 100%, as with any markup language, but certainly easier to enforce than with HTML).

Let me know if this makes sense to you or not. If it doesn't, perhaps I have my wires crossed.
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Online Reference Manual

Postby uckelman » January 23rd, 2008, 3:48 pm

Thus spake "meng":
Well module developers are users too. But as I see it there are (at least) 4
tasks here:
(1) deciding upon, and gaining familiarity with, a format for the documentati
on
(2) updating/reorganizing existing documentation
(3) generating new documentation
(4) coordination of the above efforts

So far I've concentrated on (1) and to a lesser extent (2), with a view to ma
naging (4) if no-one else objects/volunteers. timpelican has offered to make
a start on (3), which is perfect, although one could argue that that task is
more a case of fleshing out the existing wiki, which falls in the realm of (2
).

My thought is that once the new draft documentation is in the new format, the
n the tasks will be:
(5) checking for accuracy
(6) checking for consistency of format

and in regards to what rk said, the developers can do (5) and I can do (6), a
lthough (6) is somewhat a built-in feature of using DocBook (not 100%, as wit
h any markup language, but certainly easier to enforce than with HTML).

Let me know if this makes sense to you or not. If it doesn't, perhaps I have
my wires crossed.

That was helpful---I see where you're headed now.

When you have a mockup of a page or two of the Reference Manual done, I'd
like to take a look, if I could.

BTW, we need better names for these things. I think that's partly to blame
for my confusion about what you're doing.

What we're calling the Reference Manual is really a reference for the
module components available in the editor. Maybe if we called it the
Editor Reference Manual (or somesuch) that would be better.

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby meng » January 29th, 2008, 6:42 pm

I realize it's a little slow, but as I get more familiar with DocBook (and after a busy week at work last week). I have a sample XML, with images and a HTML conversion, available to whomever would like to check it out. (Combined, the images exceed the max filesize for attachment here, but I'll email the ~1MB file upon request.) The PDF conversion I've tried so far is particularly ugly (the HTML conversion is not fantastic either), but I'll keep trying other convertors.

FYI, I am using an evaluation version of <oXygen> XML editor, which speeds up my productivity no end compared to XMLmind. (Possibly I could be just as fast if I could set up vim or emacs to validate DocBook XML in a similar fashion - apparently it can be done.) At least it's cross-platform, even though it's proprietary.
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Online Reference Manual

Postby uckelman » January 29th, 2008, 6:58 pm

Thus spake "meng":
I realize it's a little slow, but as I get more familiar with DocBook (and af
ter a busy week at work last week). I have a sample XML, with images and a HT
ML conversion, available to whomever would like to check it out. (Combined, t
he images exceed the max filesize for attachment here, but I'll email the ~1M
B file upon request.) The PDF conversion I've tried so far is particularly ug
ly (the HTML conversion is not fantastic either), but I'll keep trying other
convertors.

I'd like to see it.

Something I don't understand: If neither the HTML output nor the PDF output
are any good, what output format is? Or, rather, what is the intended output
format when you're using DocBook, if it's neither HTML nor PDF?

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Postby meng » January 29th, 2008, 7:32 pm

As I understand it, it's not the idea of converting between formats that's a problem, it's the quality of the rendering itself. I think the converter I'm using right now is crap. I already emailed you the stuff.
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Postby Brent Easton » January 30th, 2008, 5:37 am

The PDF conversion I've tried so far is particularly ugly (the HTML conversion is not fantastic either), but I'll keep trying other convertors.


Perhaps we should consider writing our own XSLT for conversion to HTML and XML-FO for conversion PDF. Then we can have it exactly the way we like it :wink:

I've had a little to do with both XSLT and XML-FO in other projects and at work and it isn't that hard.

Brent.
User avatar
Brent Easton
 
Posts: 2983
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Online Reference Manual

Postby uckelman » January 30th, 2008, 9:38 am

Thus spake "Brent Easton":
The PDF conversion I've tried so far is particularly ugly (the HTML convers
ion is not fantastic either), but I'll keep trying other convertors.


Perhaps we should consider writing our own XSLT for conversion to HTML and XM
L-FO for conversion PDF. Then we can have it exactly the way we like it [Wi
nk]

I've had a little to do with both XSLT and XML-FO in other projects and at wo
rk and it isn't that hard.

Brent.

The Subversion Book has relatively nice HTML and PDF output. Maybe we
could use theirs?

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Online Reference Manual

Postby timpelican » January 30th, 2008, 12:38 pm

On Wed, January 30, 2008 5:37 am, Brent Easton wrote:

Perhaps we should consider writing our own XSLT for conversion to HTML
and XML-FO for conversion PDF. Then we can have it exactly the way we
like it [Wink]

I assumed that - or some kind of custom CSS - was going to be a later
step, to put the 'VASSAL look-and-feel' onto everything coming out of
DocBook.

Cheers,
Tim.



_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
timpelican
 
Posts: 171
Joined: January 2nd, 2008, 3:50 pm

Postby meng » February 4th, 2008, 5:14 pm

All right, since I haven't heard any strident objections to using DocBook, and I've continued doing a little work on the documentation from time to time (not heaps, I have work and family and gaming to concentrate on too, like everyone else), I'll want to make this available via subversion soon. Do I need an account for that?
meng
 
Posts: 124
Joined: January 14th, 2008, 6:35 pm
Location: Melbourne, Australia

Online Reference Manual

Postby uckelman » February 4th, 2008, 5:32 pm

Thus spake "meng":
All right, since I haven't heard any strident objections to using DocBook, an
d I've continued doing a little work on the documentation from time to time (
not heaps, I have work and family and gaming to concentrate on too, like ever
yone else), I'll want to make this available via subversion soon. Do I need a
n account for that?


Hey! Hold on! Haven't had a chance to look at what you did yet! :)

As for SVN: Yes, you need to get a sourceforge account. Once you have
that, let me know your username and I'll add you to the project and give
you SVN access.

--
J.

_______________________________________________
Messages mailing list
Messages@forums.vassalengine.org
http://forums.vassalengine.org/mailman/ ... engine.org

Post generated using Mail2Forum (http://www.mail2forum.com)
User avatar
uckelman
Site Admin
 
Posts: 8571
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

PreviousNext

Return to General Discussion

Who is online

Users browsing this forum: Google [Bot] and 3 guests