[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-devel
Subject: Re: Proposal for how to deal with documentation issues
From: "Michael Howell" <mhowell123 () gmail ! com>
Date: 2008-08-18 2:13:31
Message-ID: a2927be10808171913w71057049m847ff305b620c488 () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
> That is a good point, but I would rather see that worded as. "Docbook has
some
> features/additional markup that we use, therefore we need a way to do the
> equivalent in a wiki system."
Thanks. I'll try to word more like that.
> Most wikis allow plug-ins to be written. It will take more work but it
should
> be do-able to add all this functionality, and possibly make the output
> clearer. Currently all <guimenuitem> does is put a slightly grey box
behind it
> and then draws an arrow. It shouldn't be too hard to code that.
Good point. If we chose to use Mediawiki or something like it, extending it
for GUI documentation would probably be a good idea.
On Sun, Aug 17, 2008 at 5:28 AM, David Edmundson <david@davidedmundson.co.uk
> wrote:
> On Sunday 17 August 2008 05:26:28 Michael Howell wrote:
> > Well, some of th tools to use Docbook, and it would be easier to simply
> > somehow get Dockbook from the wiki and make use of the existing
> > infrastructure. Also, Docbook provides ways to express things that
> > Mediawiki cannot. For example, you will notice that the KDE DTD provides
> > aliases for common names such as &RMB; for right-mouse-button, or more
> > importantly, the actual markup like <gui-menu> to describe things
> commonly
> > used in
> > documentation. Moving to Mediawiki and straight HTML would allow for
> > wiki-based editing, but would regress in some ways as well. A
> docbook-based
> > wiki would be ideal, since we could continue to use the Docbook tools and
> > markup AND get wiki-based editing.
>
> That is a good point, but I would rather see that worded as. "Docbook has
> some
> features/additional markup that we use, therefore we need a way to do the
> equivalent in a wiki system." Not "Docbook has a feature we use therefore
> we
> must continue using it."
>
> Most wikis allow plug-ins to be written. It will take more work but it
> should
> be do-able to add all this functionality, and possibly make the output
> clearer. Currently all <guimenuitem> does is put a slightly grey box behind
> it
> and then draws an arrow. It shouldn't be too hard to code that.
>
> As for the aliases, I think they're mostly there to keep consistency and
> speed
> up translation. I've no idea how we can easily fix this. Thoughts?
>
> For those interested a complete list of the KDE Docbook markup can be found
> at: http://l10n.kde.org/docs/markup/index.html
>
> >
> > On Sat, Aug 16, 2008 at 4:22 PM, Michael Pyne <mpyne@purinchu.net>
> wrote:
> > > On Saturday 16 August 2008, Michael Howell wrote:
> > >
> > > First off, please don't just reply and dump all the text you're
> replying
> > > to after your response. If it's important enough to include in the
> reply
> > > it's important enough to quote before your response that way there's
> > > context with your message.
> > >
> > > > It would seem necessary to use something other than Mediawiki, since
> > > >
> > > > Mediawiki can't really map to Docbook. The KDE Docbook can contain
> > > >
> > > > information that Mediawiki cannot express. Yes, it would mean using a
> > > >
> > > > Docbook-based wiki. Is there one?
> > >
> > > Well you're overthinking it I think.
> > >
> > > What we want is presumably some way to create an offline records of
> these
> > > docs, right? Available in different translations?
> > >
> > > Couldn't we simply dump the Wiki into static .html files and call it
> > > good? We use DocBook as a means to an end, if we find a better way to
> > > achieve that end then it's worth asking if we still need DocBook.
> > >
> > > Maybe that's not the best way to go about it but don't get caught up in
> > > "it must be DocBook" unless there's other good reasons (i.e. the rest
> of
> > > our tools need DocBook, etc.)
> > >
> > > Regards,
> > >
> > > - Michael Pyne
> > >
> > > >> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to
> > >
> > > unsubscribe <<
>
>
>
> >> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to
> unsubscribe <<
>
>
--
Michael Howell
mhowell123@gmail.com
[Attachment #5 (text/html)]
<div dir="ltr">> That is a good point, but I would rather see that worded as. \
"Docbook has some<br> > features/additional markup that we use, therefore we \
need a way to do the<br> > equivalent in a wiki system."<br>Thanks. I'll \
try to word more like that.<br><br>> Most wikis allow plug-ins to be written. It \
will take more work but it should<br> > be do-able to add all this functionality, \
and possibly make the output<br> > clearer. Currently all <guimenuitem> does \
is put a slightly grey box behind it<br> > and then draws an arrow. It \
shouldn't be too hard to code that.<br>Good point. If we chose to use Mediawiki \
or something like it, extending it for GUI documentation would probably be a good \
idea.<br><br><div class="gmail_quote"> On Sun, Aug 17, 2008 at 5:28 AM, David \
Edmundson <span dir="ltr"><<a \
href="mailto:david@davidedmundson.co.uk">david@davidedmundson.co.uk</a>></span> \
wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, \
204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> <div class="Ih2E3d">On Sunday \
17 August 2008 05:26:28 Michael Howell wrote:<br> </div><div class="Ih2E3d">> \
Well, some of th tools to use Docbook, and it would be easier to simply<br> > \
somehow get Dockbook from the wiki and make use of the existing<br> > \
infrastructure. Also, Docbook provides ways to express things that<br> > Mediawiki \
cannot. For example, you will notice that the KDE DTD provides<br> > aliases for \
common names such as &RMB; for right-mouse-button, or more<br> > importantly, \
the actual markup like <gui-menu> to describe things commonly<br> > used \
in<br> > documentation. Moving to Mediawiki and straight HTML would allow for<br>
> wiki-based editing, but would regress in some ways as well. A docbook-based<br>
> wiki would be ideal, since we could continue to use the Docbook tools and<br>
> markup AND get wiki-based editing.<br>
<br>
</div>That is a good point, but I would rather see that worded as. "Docbook has \
some<br> features/additional markup that we use, therefore we need a way to do \
the<br> equivalent in a wiki system." Not "Docbook has a feature we use \
therefore we<br> must continue using it."<br>
<br>
Most wikis allow plug-ins to be written. It will take more work but it should<br>
be do-able to add all this functionality, and possibly make the output<br>
clearer. Currently all <guimenuitem> does is put a slightly grey box behind \
it<br> and then draws an arrow. It shouldn't be too hard to code that.<br>
<br>
As for the aliases, I think they're mostly there to keep consistency and \
speed<br> up translation. I've no idea how we can easily fix this. Thoughts?<br>
<br>
For those interested a complete list of the KDE Docbook markup can be found<br>
at: <a href="http://l10n.kde.org/docs/markup/index.html" \
target="_blank">http://l10n.kde.org/docs/markup/index.html</a><br> \
<div><div></div><div class="Wj3C7c"><br> ><br>
> On Sat, Aug 16, 2008 at 4:22 PM, Michael Pyne <<a \
href="mailto:mpyne@purinchu.net">mpyne@purinchu.net</a>> wrote:<br> > > \
On Saturday 16 August 2008, Michael Howell wrote:<br> > ><br>
> > First off, please don't just reply and dump all the text you're \
replying<br> > > to after your response. If it's important enough to \
include in the reply<br> > > it's important enough to quote before your \
response that way there's<br> > > context with your message.<br>
> ><br>
> > > It would seem necessary to use something other than Mediawiki, \
since<br> > > ><br>
> > > Mediawiki can't really map to Docbook. The KDE Docbook can \
contain<br> > > ><br>
> > > information that Mediawiki cannot express. Yes, it would mean using \
a<br> > > ><br>
> > > Docbook-based wiki. Is there one?<br>
> ><br>
> > Well you're overthinking it I think.<br>
> ><br>
> > What we want is presumably some way to create an offline records of \
these<br> > > docs, right? Available in different translations?<br>
> ><br>
> > Couldn't we simply dump the Wiki into static .html files and call \
it<br> > > good? We use DocBook as a means to an end, if we find a better way \
to<br> > > achieve that end then it's worth asking if we still need \
DocBook.<br> > ><br>
> > Maybe that's not the best way to go about it but don't get caught \
up in<br> > > "it must be DocBook" unless there's other good \
reasons (i.e. the rest of<br> > > our tools need DocBook, etc.)<br>
> ><br>
> > Regards,<br>
> ><br>
> > - Michael Pyne<br>
> ><br>
> > >> Visit <a \
href="http://mail.kde.org/mailman/listinfo/kde-devel#unsub" \
target="_blank">http://mail.kde.org/mailman/listinfo/kde-devel#unsub</a> to<br> > \
><br> > > unsubscribe <<<br>
<br>
</div></div><br><br>
>> Visit <a href="http://mail.kde.org/mailman/listinfo/kde-devel#unsub" \
target="_blank">http://mail.kde.org/mailman/listinfo/kde-devel#unsub</a> to \
unsubscribe <<<br> <br></blockquote></div><br><br clear="all"><br>-- \
<br>Michael Howell<br><a \
href="mailto:mhowell123@gmail.com">mhowell123@gmail.com</a><br> </div>
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic