From: Tim E. R. <ter...@ro...> - 2013-02-22 07:32:38
|
(To quote the infamous Bugs Bunny.) As requested: New: Install three kinds of pre-built documentation: PDF + single/split HMTL docs. I separated the developer docs from the user docs. Flo, I split the HTML at 'Depth' = 4 and it comes out pretty cool looking I think. Y'all can play around with the depth by changing... a handy build *script* which I added. The build script is /doc/build_docs.sh You'll likely want to use it or a variant to get the HTML .aux files for proper link display instead of little squares. Er, you will need *both* pdflatex AND latex2html to run the script. Oops, be careful, it first erases *both* existing PDF and HTML pre-built files. I should change that to allow a choice... Feel free to modify that script while I grab some shut-eye for the night. And I install both the PDF and HTML, via the cmake scripts. I don't know if an error would occur if either or both were *not* present. I'll look again. Still, if you /are/ developing docs, you want to test the HTML don't you... ------ Fixed table in my Appendix in tex file so it works with HTML. Removed all old docs from tree and SVN repo. For now, I've changed F1 help to open PDF, if not found fallback to HTML. I've #define MUSE_USE_PDF_HELP_FILE in help.cpp. Undefine for HTML only. Later, we may at least need to keep track of viewer process (don't open copies), also try context-sensitive help by using a library or Qt HTML features. The Help opener (F1) has always been LANG ready (looks for _xx) and I've added PDF to that opener now too, but this new build script is not 'automatic' LANG aware, per-se. Maybe after translating the tex, a person could just rename the generated PDF or HTML files with the _xx extensions. TODO: The generated HTML developer docs contain some nonsense. Unknown formatters? Florian any ideas there? Guys? Anyway, hope this is a decent start for new docs. Tim. |
From: Tim E. R. <ter...@ro...> - 2013-02-23 04:55:58
|
On February 22, 2013 02:32:19 AM Tim E. Real wrote: > ... ... also try context-sensitive help by using a library > or Qt HTML features. Ah yes, I knew there had to be something since Qt Designer has it: http://qt-project.org/doc/qt-4.8/qthelp-framework.html There is the answer for sure. Don't re-invent the wheel. It is sophisticated, handles some tricky problems and they put a lot into it, but it's fairly straightforward. It does indexing with full-text searches, QtAssistant vs. embedded help viewing etc. It relies, of course, on a cross-reference list (an XML file), which can do much more than that. The only thing that worries me is that I suspect the list would quickly become out of date if we're not careful to maintain it. And it *only* works with HTML files. It does not handle PDFs. (I can see now that homegrown PDF support would be difficult.) Well there it is folks, if we want to use it. Tim. |
From: Florian J. <flo...@we...> - 2013-04-12 16:17:33
Attachments:
signature.asc
|
Am 23.02.2013 05:55, schrieb Tim E. Real: > On February 22, 2013 02:32:19 AM Tim E. Real wrote: > >> ... ... also try context-sensitive help by using a library >> or Qt HTML features. > > Ah yes, I knew there had to be something since Qt Designer has it: > > http://qt-project.org/doc/qt-4.8/qthelp-framework.html > > There is the answer for sure. Don't re-invent the wheel. > > It is sophisticated, handles some tricky problems and they > put a lot into it, but it's fairly straightforward. > > It does indexing with full-text searches, QtAssistant vs. embedded > help viewing etc. > > It relies, of course, on a cross-reference list (an XML file), > which can do much more than that. > The only thing that worries me is that I suspect the list would > quickly become out of date if we're not careful to maintain it. > > And it *only* works with HTML files. It does not handle PDFs. > > (I can see now that homegrown PDF support would be difficult.) > > Well there it is folks, if we want to use it. we do want! are there any beginnings on this already? if not, i could probably quickly hack together some help infrastructure, just populating it with helpful information will take long and require your help. flo > > Tim. > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today: > http://p.sf.net/sfu/appdyn_d2d_feb > _______________________________________________ > Lmuse-developer mailing list > Lmu...@li... > https://lists.sourceforge.net/lists/listinfo/lmuse-developer > |
From: Tim E. R. <ter...@ro...> - 2013-04-12 19:47:42
|
On April 12, 2013 06:17:11 PM Florian Jung wrote: > Am 23.02.2013 05:55, schrieb Tim E. Real: > > On February 22, 2013 02:32:19 AM Tim E. Real wrote: > >> ... ... also try context-sensitive help by using a library > >> > >> or Qt HTML features. > > > > Ah yes, I knew there had to be something since Qt Designer has it: > > > > http://qt-project.org/doc/qt-4.8/qthelp-framework.html > > > > There is the answer for sure. Don't re-invent the wheel. > > > > It is sophisticated, handles some tricky problems and they > > > > put a lot into it, but it's fairly straightforward. > > > > It does indexing with full-text searches, QtAssistant vs. embedded > > > > help viewing etc. > > > > It relies, of course, on a cross-reference list (an XML file), > > > > which can do much more than that. > > > > The only thing that worries me is that I suspect the list would > > > > quickly become out of date if we're not careful to maintain it. > > > > And it *only* works with HTML files. It does not handle PDFs. > > > > (I can see now that homegrown PDF support would be difficult.) > > > > Well there it is folks, if we want to use it. > > we do want! > are there any beginnings on this already? No not at all, from my side. > if not, i could probably quickly hack together some help infrastructure, > just populating it with helpful information will take long and require > your help. Sure, do read the docs, it does have some powerful features so we want to make sure we do it right. Tim. > > flo > > > Tim. > > |
From: Tim E. R. <ter...@ro...> - 2013-03-01 08:13:27
|
Browsing some header files, I'm reminded: "Doxygen is the de facto standard tool for generating documentation from annotated C++ sources" "Doxygen can help you in three ways: It can generate an on-line documentation browser (in HTML) and/or an off- line reference manual (in LaTeX) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically. You can also use doxygen for creating normal documentation... " I removed Doxygen because it was unused and user shouldn't need it. But for us devs... Doxygen usage is very sparse in MusE. Still, a few places have it. I never used it in code. I should read up on it. If someone wanted to work on developer docs, could these LaTeX files be linked with our existing separate developer_docs.tex ? Sounds to me like we should be using Doxygen, like a 'central' docs 'factory' to create all our documentation, including user docs and man pages. I suppose it matters not how a particular dev generates all these pre-built docs, but we would like to help with scripts and so on for the devs, so maybe if we concentrate on Doxygen. I'd love to see the visual dependency graph of modern MusE. (The Old KDevelop 3 series used to show the graph.) I'll poke around see what I can do... Tim. On February 22, 2013 02:32:19 AM Tim E. Real wrote: > (To quote the infamous Bugs Bunny.) > > As requested: > > New: Install three kinds of pre-built documentation: > PDF + single/split HMTL docs. > > I separated the developer docs from the user docs. > > Flo, I split the HTML at 'Depth' = 4 and it comes out > pretty cool looking I think. > Y'all can play around with the depth by changing... > > a handy build *script* which I added. > > The build script is /doc/build_docs.sh You'll likely want to use it > or a variant to get the HTML .aux files for proper link display > instead of little squares. > > Er, you will need *both* pdflatex AND latex2html to run the script. > > Oops, be careful, it first erases *both* existing PDF and HTML pre-built > files. I should change that to allow a choice... > Feel free to modify that script while I grab some shut-eye for the night. > > And I install both the PDF and HTML, via the cmake scripts. > I don't know if an error would occur if either or both were > *not* present. I'll look again. > > Still, if you /are/ developing docs, you want to test the HTML don't you... > > ------ > Fixed table in my Appendix in tex file so it works with HTML. > > Removed all old docs from tree and SVN repo. > > For now, I've changed F1 help to open PDF, if not found fallback to HTML. > I've #define MUSE_USE_PDF_HELP_FILE in help.cpp. Undefine for HTML only. > Later, we may at least need to keep track of viewer process > (don't open copies), also try context-sensitive help by using a library > or Qt HTML features. > > The Help opener (F1) has always been LANG ready (looks for _xx) > and I've added PDF to that opener now too, but this new build script is > not 'automatic' LANG aware, per-se. > Maybe after translating the tex, a person could just rename the generated > PDF or HTML files with the _xx extensions. > > TODO: The generated HTML developer docs contain some nonsense. > Unknown formatters? Florian any ideas there? Guys? > > Anyway, hope this is a decent start for new docs. > Tim. > > |