Re: [CMake] Improvements for cross-referencing in the documentation?
2011/1/27 Alexander Neundorf : > 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?
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?
> 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: > Am 26.01.2011 17:44, schrieb Alexander Neundorf: > > On Wednesday 26 January 2011, SF Markus Elfring wrote: > >>> E.g. cmake --help-full.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?
Am 26.01.2011 17:44, schrieb Alexander Neundorf: On Wednesday 26 January 2011, SF Markus Elfring wrote: E.g. cmake --help-full.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?
On Wednesday 26 January 2011, SF Markus Elfring wrote: > > E.g. cmake --help-full.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?
E.g. cmake --help-full.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 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 .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?
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?
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 ">
${mainIndexFile}
echo "\"http://www.w3.org/TR/html4/loose.dtd\";>" >> ${mainIndexFile}
echo "" >> ${mainIndexFile}
echo " "
>> ${mainIndexFile}
echo "CMake Documentation" >> ${mainIndexFile}
echo "" >>
${mainIndexFile}
echo "" >> ${mainIndexFile}
echo "" >> ${mainIndexFile}
echo "" >> ${mainIndexFile}
#
# Start the Qt adp file
#
echo "" > ${adpFile}
echo "" > ${adpFile}
echo "" >> ${adpFile}
echo " CMake Documentation" >> ${adpFile}
echo " CMake Docs" >> ${adpFile}
#echo " " >> ${adpFile}
echo " index.html" >> ${adpFile}
echo " About CMake Docs Viewer"
>> ${adpFile}
#echo " about.txt" >> ${adpFile}
#echo " ." >> ${adpFile}
echo " " >> ${adpFile}
echo "" >> ${adpFile}
echo "" >> ${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 ">
${indexFile}
echo "\"http://www.w3.org/TR/html4/loose.dtd\";>" >> ${indexFile}
echo "" >> ${indexFile}
echo "
" >> ${indexFile}
echo "CMake ${1} Index" >> ${indexFile}
echo ""
>> ${indexFile}
echo "" >> ${indexFile}
echo "" >> ${indexFile}
echo "" >> ${indexFile}
echo "All CMake Documentation" >>
${indexFile}
#
# Create a section in the .adp file
#
echo " " >>
${adpFile}
#
# Create a section in the top level index file
#
echo "CMake ${1}s" >>
${mainIndexFile}
#
# Generate all the individual documentation html files
#
rm $tmpSortFile
touch ${tmpSortFile}
i=0
exec 9<${listFile}
while read -u 9 line
do
if [[ ${i} -gt 0 ]]; then
echo "${line}" >> ${tmpSortFile}
fi
let i=i+1
done
exec 9<&-
# Now sort the file
echo "Sorting the List of ${1}"
sort ${tmpSortFile} --output=${listFile}
# Now read the file and get the docs for the command, variable etc.
i=0
exec 8<${listFile}
while read -u 8 line
do
#if [[ ${i} -gt 0 ]]; then
echo ${i}": ${line}"
# Seems that CMake only puts out the body portion
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
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 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?
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: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?
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
