For writing user documentation - what tools do you suggest?

[Wolf P.]

I was hoping to use DocBook. Or is there a much better way with the Qt SDK?

:) Thanks in advance for your tipps!

[jsiei97]

To do code documentation I use Doxygen, that generates some nice LaTeX (or html) output.

Then you can use LaTeX to write some documentation that links into the Doxygen generated ones quite easy.

And at the end it all becomes some nice looking pdf:s. This is a powerful way to do it with a possibility to autogenerate a lot of the information but the learning curve is....

[Wolf P.]

[quote author="jsiei97" date="1291882095"]To do code documentation I use Doxygen, that generates some nice LaTeX (or html) output.[/quote] Oh sorry, I was not asking for code (say API) documentation, but for documentation for users of my software (handbooks, tutorials etc.). I read, that doxygen can be used for that as well, but this seems a bit strange to me for now. I saw excellent multilingual multi-target DocBook generated documentations for example

• "The Subversion Book":http://svnbook.red-bean.com/ (html, pdf)
• "TortoiseSVN docs":http://tortoisesvn.net/support.html (html, pdf, chm)

I don't believe that I'm able make it from the Qt source files without decreasing their usability.

[miracules]

You could always use qdoc. That is what we use for our documentation. If you go to http://doc.qt.nokia.com/qdoc/ you will find the manual.

QDoc is part of the Qt package and provides you features that let you write documentation both for APIs but also for manuals using a simple markup language.

You can go into the application and change the templates and configurations so that you can get your own look and feel. However, that requires you to know some HTML and CSS.

[Wolf P.]

Morton, thanks for the tipp. Will I be able to generate CHM (Microsoft compiled Help) files with qdoc?

[kamalakshantv]

[quote author="Morten Engvoldsen" date="1291890184"]You could always use qdoc. That is what we use for our documentation. If you go to http://doc.qt.nokia.com/qdoc/ you will find the manual.

QDoc is part of the Qt package and provides you features that let you write documentation both for APIs but also for manuals using a simple markup language.

You can go into the application and change the templates and configurations so that you can get your own look and feel. However, that requires you to know some HTML and CSS.[/quote]

Would like to know if Qt documentation would be made available as a chm file. Or we could only download the documentation separately.

[miracules]

@Wolf: You can use the help module for this. Please have a look at http://doc.qt.nokia.com/4.7-snapshot/qthelp.html for more uhm.. help :)

@QtK There are currently no plans to generate it into chm format. However, you are welcome to request it in our bug tracker. :)

Cheers,
Morten

[kamalakshantv]

[quote author="Morten Engvoldsen" date="1291900656"]@Wolf: You can use the help module for this. Please have a look at http://doc.qt.nokia.com/4.7-snapshot/qthelp.html for more uhm.. help :)

@QtK There are currently no plans to generate it into chm format. However, you are welcome to request it in our bug tracker. :)

Cheers,
Morten[/quote]

Is it due to any license issue or something like that. .chm being Microsoft proprietary format.

[Franzk]

Doxygen does everything nicely (it is pretty much a qdoc clone if I recall correctly). It can also create chm files if you wish.

[kamalakshantv]

[quote author="Franzk" date="1291903160"]Doxygen does everything nicely (it is pretty much a qdoc clone if I recall correctly). It can also create chm files if you wish.[/quote]

For chm you need some sort of 3rd party extension I guess.

[Wolf P.]

Yes, you need the MS help workshop, but it's free.

[Wolf P.]

[quote author="Morten Engvoldsen" date="1291900656"]@Wolf: You can use the help module for this. Please have a look at http://doc.qt.nokia.com/4.7-snapshot/qthelp.html for more uhm.. help :)
[/quote] Oh, thanks :)

[GordonSchumacher]

Morten - this is for my own curiosity, not as a challenge... can you tell me why you would recommend qdoc3 instead of doxygen, now that doxygen can generate qch files?

[baysmith]

[quote author="GordonSchumacher" date="1292034475"]Morten - this is for my own curiosity, not as a challenge... can you tell me why you would recommend qdoc3 instead of doxygen, now that doxygen can generate qch files?[/quote]

I'm curious too, since I've seen links to "this":http://qt.gitorious.org/qt/qt/blobs/master/tools/qdoc3/README.TXT which implies that qdoc is not recommended.

[Wolf P.]

Can anyone post a link to an open source project that uses doxygen for user documentation?

[stukdev]

"MediaWiki":http://svn.wikimedia.org/doc/
"Apache Armony":http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html

[quote author="Wolf P." date="1292094960"]Can anyone post a link to an open source project that uses doxygen for user documentation?[/quote]

[Wolf P.]

Thanks, but this seems to be API docs...

[stukdev]

Oh sorry, mistake you want a source code with an example of the api.
So look the "qextserial":http://qextserialport.sourceforge.net/ project, it is a project to use serial port with qt.
This project have documentation in doxygen and if you download the source you see the doxygen comment in the source.

This is an example

@

/*!
\class QextSerialBase
\version 1.0.0
\author Stefan Sander

A common base class for Win_QextSerialBase, Posix_QextSerialBase and QextSerialPort.
/
#ifdef QT_THREAD_SUPPORT
QMutex QextSerialBase::mutex=NULL;
unsigned long QextSerialBase::refCount=0;
#endif

/*!
\fn QextSerialBase::QextSerialBase()
Default constructor.
*/
QextSerialBase::QextSerialBase()
: QIODevice()
{

#ifdef TTY_WIN
setPortName("COM1");

#elif defined(TTY_IRIX)
setPortName("/dev/ttyf1");

#elif defined(TTY_HPUX)
setPortName("/dev/tty1p0");

#elif defined(TTY_SUN)
setPortName("/dev/ttya");

#elif defined(TTY_DIGITAL)
setPortName("/dev/tty01");

#elif defined(TTY_FREEBSD)
setPortName("/dev/ttyd1");

#else
setPortName("/dev/ttyS0");
#endif

construct();

}

/*!
\fn QextSerialBase::QextSerialBase(const QString & name)
Construct a port and assign it to the device specified by the name parameter.
*/
QextSerialBase::QextSerialBase(const QString & name)
: QIODevice()
{
setPortName(name);
construct();
}

/*!
\fn QextSerialBase::~QextSerialBase()
Standard destructor.
*/
QextSerialBase::~QextSerialBase()
{

#ifdef QT_THREAD_SUPPORT
refCount--;
if (mutex && refCount==0) {
delete mutex;
mutex=NULL;
}
#endif

}

/*!
\fn void QextSerialBase::construct()
Common constructor function for setting up default port settings.
(115200 Baud, 8N1, Hardware flow control where supported, otherwise no flow control, and 500 ms timeout).
*/
void QextSerialBase::construct()
{
Settings.BaudRate=BAUD115200;
Settings.DataBits=DATA_8;
Settings.Parity=PAR_NONE;
Settings.StopBits=STOP_1;
Settings.FlowControl=FLOW_HARDWARE;
Settings.Timeout_Sec=0;
Settings.Timeout_Millisec=500;

#ifdef QT_THREAD_SUPPORT
if (!mutex) {
mutex=new QMutex( QMutex::Recursive );
}
refCount++;
#endif

setOpenMode(QIODevice::NotOpen);
}

/*!
\fn void QextSerialBase::setPortName(const QString & name)
Sets the name of the device associated with the object, e.g. "COM1", or "/dev/ttyS0".
*/
void QextSerialBase::setPortName(const QString & name)
{
port = name;
}
@

[quote author="Wolf P." date="1292253770"]Thanks, but this seems to be API docs...[/quote]