Re: [CMake] Improvements for cross-referencing in the documentation?
On Thursday 27 January 2011, SF Markus Elfring wrote: Am 26.01.2011 17:44, schrieb Alexander Neundorf: On Wednesday 26 January 2011, SF Markus Elfring wrote: E.g. cmake --help-fullfilename.docbook gives you a docbook file, which can then be processed further. The interesting thing is how to get the links into these files initially. Do you need any intermediate format(s) for the desired data exchange? Sorry, which desired data exchange ? A source format will be converted to a different file format and the conversion result will be distributed to the users, won't it? Hmm. The doc source is embedded in the code, i.e. the docs for the modules are at the top of the modules, the docs for the commands is in the commands C++ implementation. I thought this discussion is about adding more markup tags to the cmake documentation ? I'm sorry. - Have I overlooked in the CMake module documentation that tags are already supported? Well, you can have normal text and you can have monospaced font (line indented). That's it currently. I think adding something like wiki markup for bold, italic and maybe links would be nice and sounds doable. Alex ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
That's it currently. Is it possible that a field or attribute can specify a format identifier (in the near future)? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Thursday 27 January 2011, SF Markus Elfring wrote: That's it currently. Is it possible that a field or attribute can specify a format identifier (in the near future)? AFAIK nothing is planned. With sounds doable I meant that this looks like a nice task which can be done without knowing a lot of the internals of cmake by somebody who has just a little time to spend (like e.g. me or others here on the list). Alex ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
2011/1/27 Alexander Neundorf a.neundorf-w...@gmx.net: On Thursday 27 January 2011, SF Markus Elfring wrote: That's it currently. Is it possible that a field or attribute can specify a format identifier (in the near future)? AFAIK nothing is planned. With sounds doable I meant that this looks like a nice task which can be done without knowing a lot of the internals of cmake by somebody who has just a little time to spend (like e.g. me or others here on the list). May be using something reStructuredText would be nice: http://en.wikipedia.org/wiki/ReStructuredText http://docutils.sourceforge.net/rst.html It has the advantage to be readable and contains basic text markup. I don't know if there is some rst2html lib that oculd be incorporated into cmake code in order to handle the cmake --help-html case but at least it is easy to use it inside plain text string. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
E.g. cmake --help-fullfilename.docbook gives you a docbook file, which can then be processed further. The interesting thing is how to get the links into these files initially. Do you need any intermediate format(s) for the desired data exchange? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Wednesday 26 January 2011, SF Markus Elfring wrote: E.g. cmake --help-fullfilename.docbook gives you a docbook file, which can then be processed further. The interesting thing is how to get the links into these files initially. Do you need any intermediate format(s) for the desired data exchange? Sorry, which desired data exchange ? I thought this discussion is about adding more markup tags to the cmake documentation ? Alex ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
Am 26.01.2011 17:44, schrieb Alexander Neundorf: On Wednesday 26 January 2011, SF Markus Elfring wrote: E.g. cmake --help-fullfilename.docbook gives you a docbook file, which can then be processed further. The interesting thing is how to get the links into these files initially. Do you need any intermediate format(s) for the desired data exchange? Sorry, which desired data exchange ? A source format will be converted to a different file format and the conversion result will be distributed to the users, won't it? I thought this discussion is about adding more markup tags to the cmake documentation ? I'm sorry. - Have I overlooked in the CMake module documentation that tags are already supported? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
I use the following script to generate a QtAssistant based documentation set.
This allows quick searching of the docs and a more organized CMake
documentation package. Here is the bash script. Maybe some else will find it
useful also. I'll be the first to admit that I am not the best/most efficient
script writer but it does work.
# START SCRIPT
#!/bin/bash
# This is a shell script to generate a QtAssistant set of docs from the CMake
distribution.
#
# Couple of things to get you started with this file:function file
# All the files are generated in the /tmp directory. If you want them
somewhere else
# set the 'generationDir' variable
qtassistant=$QTDIR/bin/Assistant_adp.app/Contents/MacOS/assistant_adp
CMAKE=`which cmake`
generationDir=/tmp/CMakeDocs
assistantDir=${generationDir}/cmake_assistant_docs
# remove any previous builds of the docs
rm -rf ${assistantDir}
mkdir -p ${assistantDir}
adpFile=${assistantDir}/CMakeDocs.adp
tmpHTMLFile=${generationDir}/temp.html
tmpSortFile=${generationDir}/sorted.txt
#-- Create a shell script to launch QtAssistant once everything is built
ShellScriptPath=/Users/mjackson/Library/ShellScripts
echo ${QTDIR}/bin/Assistant_adp.app/Contents/MacOS/assistant_adp -profile
$generationDir/cmake_assistant_docs/CMakeDocs.adp
$ShellScriptPath/cmakedocs.sh
chmod ugo+rwx $ShellScriptPath/cmakedocs.sh
#css_sheet=http://www.kitware.com/kitware.css;
css_sheet=./cmake.css
#
# Start the main index.html file that lists the major doc groups, Commands,
Modules, Variables
#
mainIndexFileName=index.html
mainIndexFile=${assistantDir}/${mainIndexFileName}
echo ${mainIndexFile}
echo !DOCTYPE HTML PUBLIC \-//W3C//DTD HTML 4.01 Transitional//EN\
${mainIndexFile}
echo \http://www.w3.org/TR/html4/loose.dtd\; ${mainIndexFile}
echo htmlhead ${mainIndexFile}
echo META http-equiv=\Content-Type\ content=\text/html; charset=UTF-8\
${mainIndexFile}
echo titleCMake Documentation/title ${mainIndexFile}
echo link href=\$css_sheet\ rel=\stylesheet\ type=\text/css\ /
${mainIndexFile}
echo /head ${mainIndexFile}
echo body ${mainIndexFile}
echo div id=\ContentTxtProd\ ${mainIndexFile}
#
# Start the Qt adp file
#
echo ${adpFile}
echo assistantconfig version=\3.2.0\ ${adpFile}
echo profile ${adpFile}
echo property name=\name\CMake Documentation/property ${adpFile}
echo property name=\title\CMake Docs/property ${adpFile}
#echo property name=\applicationicon\/property ${adpFile}
echo property name=\startpage\index.html/property ${adpFile}
echo property name=\aboutmenutext\About CMake Docs Viewer/property
${adpFile}
#echo property name=\abouturl\about.txt/property ${adpFile}
#echo property name=\cmake_docs\./property ${adpFile}
echo /profile ${adpFile}
echo ${adpFile}
echo DCF ref=\${mainIndexFileName}\ icon=\\ imagedir=\\
title=\CMake Docs Handbook\ ${adpFile}
#
# Function GenerateDocsForCommand This function will create all the
# individual html files, an index file and the proper section of the .adp file
# $1 The type of docs we are going to generate 'command' 'module' 'variable'
function GenerateDocsForCommand()
{
docDirName=cmake_${1}_docs
docDir=${assistantDir}/${docDirName}
mkdir ${docDir}
listFile=${generationDir}/list.txt
${CMAKE} --help-${1}-list ${listFile}
echo * Generating HTML files for command '${1}'
#
# Start the Index File for this group of docs
#
indexFile=${docDir}/cmake_${1}_index.html
echo ${indexFile}
echo !DOCTYPE HTML PUBLIC \-//W3C//DTD HTML 4.01 Transitional//EN\
${indexFile}
echo \http://www.w3.org/TR/html4/loose.dtd\; ${indexFile}
echo htmlhead ${indexFile}
echo META http-equiv=\Content-Type\ content=\text/html; charset=UTF-8\
${indexFile}
echo titleCMake ${1} Index/title ${indexFile}
echo link href=\../$css_sheet\ rel=\stylesheet\ type=\text/css\ /
${indexFile}
echo /head ${indexFile}
echo body ${indexFile}
echo div id=\ContentTxtProd\ ${indexFile}
echo pa href=\../index.html\All CMake Documentation/a/p
${indexFile}
#
# Create a section in the .adp file
#
echo section ref=\${indexFile}\ title=\CMake ${1}s\
${adpFile}
#
# Create a section in the top level index file
#
echo pa target=\DocFrame\
Re: [CMake] Improvements for cross-referencing in the documentation?
Currently, for formatting the format as described in the readme.txt in the CMake modules directory is used (i.e. not that much formatting). Do higher level programming interfaces exist that can work with message/documentation templates in various file formats? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Tuesday 25 January 2011, SF Markus Elfring wrote: Currently, for formatting the format as described in the readme.txt in the CMake modules directory is used (i.e. not that much formatting). Do higher level programming interfaces exist that can work with message/documentation templates in various file formats? Not quite sure what you mean. You can get plain text, man, html and docbook help output from cmake. E.g. cmake --help-full filename.docbook gives you a docbook file, which can then be processed further. The interesting thing is how to get the links into these files initially. Alex ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
Much to my surprise, there was only a single CMAKE_MATCH on our whole documentation page. It would make sense to document the variables CMAKE_MATCH_0 and friends explicitly. And cross-referencing left, right, north and south would also be good. Does the current documentation format support detailed cross-referencing (with hyperlinks)? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Mon, Jan 24, 2011 at 11:01 AM, SF Markus Elfring elfr...@users.sourceforge.net wrote: Much to my surprise, there was only a single CMAKE_MATCH on our whole documentation page. It would make sense to document the variables CMAKE_MATCH_0 and friends explicitly. And cross-referencing left, right, north and south would also be good. Does the current documentation format support detailed cross-referencing (with hyperlinks)? No, it does not. Any cross-references are mentioned in text only form and depend on the end user finding the cross-reference topic. Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
No, it does not. Any cross-references are mentioned in text only form and depend on the end user finding the cross-reference topic. Would you like to change this situation? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Mon, Jan 24, 2011 at 11:10 AM, SF Markus Elfring elfr...@users.sourceforge.net wrote: No, it does not. Any cross-references are mentioned in text only form and depend on the end user finding the cross-reference topic. Would you like to change this situation? Regards, Markus I would, but it's a tall order that will take hours and hours of work on someone's behalf, and I cannot sign up for the task at the moment. We already have this bug filed to improve CTest and CPack documentation: http://public.kitware.com/Bug/view.php?id=10067 Perhaps if you have concrete suggestions for cross-referencing, appending notes to that bug would be a good idea. Thanks, David ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
We already have this bug filed to improve CTest and CPack documentation: http://public.kitware.com/Bug/view.php?id=10067 I guess that the selection of a proper documentation format is a general problem for all applications. Which are your format favourites for CMake components at the moment? Regards, Markus ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
Re: [CMake] Improvements for cross-referencing in the documentation?
On Monday 24 January 2011, SF Markus Elfring wrote: We already have this bug filed to improve CTest and CPack documentation: http://public.kitware.com/Bug/view.php?id=10067 I guess that the selection of a proper documentation format is a general problem for all applications. Which are your format favourites for CMake components at the moment? Currently, for formatting the format as described in the readme.txt in the CMake modules directory is used (i.e. not that much formatting). This is parsed in cmake and then translated to html, plain text and man pages. This parser would have to be extended. E.g. also having an *emphasized* or _emphasized_ tag would be nice. Alex ___ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://www.cmake.org/mailman/listinfo/cmake
