Re: Broken refs
On Thu, Aug 06, 2009 at 09:50:56AM +0100, Trevor Daniels wrote:
I've just pushed another fix for broken refs resulting from your doc
reorganisation.
Oops, I forgot that I need to touch foo.tely before testing.
That said, it would only find the broken @ref, not the broken
@rprogram stuff.
As there seems to be no replacement nodes all I can do
is comment them out with a FIXME. Any chance you could add replacement
nodes as you go so we can fix the links properly rather than scattering
FIXMEs throughout the docs?
Not until we have @rweb or @rgeneral or whatever it gets called.
At least, that's what the @ref{Setup for MacOS X} are waiting for.
I admit that I could fix the @rprogram{LilyPond-book} link right
now if it was a priority.
One possible idea would be to add your ref-checking script to the
source tree, so that I could find and comment out these sections
myself... but IIRC, John was going to add such reference-checking
to the build script itself.
Basically, the doc build process is in flux at the moment. If
symptoms persist for longer than a week, we'll call a doctor. :)
Cheers,
- Graham
___
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
Graham Percival wrote Thursday, August 06, 2009 10:06 AM
On Thu, Aug 06, 2009 at 09:50:56AM +0100, Trevor Daniels wrote:
I've just pushed another fix for broken refs resulting from your
doc
reorganisation.
Oops, I forgot that I need to touch foo.tely before testing.
That said, it would only find the broken @ref, not the broken
@rprogram stuff.
Aah, I should have checked more carefully. The
@rprogram broken link was caused by your dropping
the capital L P from LilyPond-book in the node
name. I've just pushed the correct fix for this.
As there seems to be no replacement nodes all I can do
is comment them out with a FIXME. Any chance you could add
replacement
nodes as you go so we can fix the links properly rather than
scattering
FIXMEs throughout the docs?
Not until we have @rweb or @rgeneral or whatever it gets called.
At least, that's what the @ref{Setup for MacOS X} are waiting for.
I admit that I could fix the @rprogram{LilyPond-book} link right
now if it was a priority.
No, not a priority. They're all listed in a
couple of commits so far, so can be traced
without too much trouble.
One possible idea would be to add your ref-checking script to the
source tree, so that I could find and comment out these sections
myself... but IIRC, John was going to add such reference-checking
to the build script itself.
It's a python program. I could send it to
you, but I didn't write it for general use
so I'm not too keen on adding it to the source
tree without some tidying up. There are a
few cludges to get round the lack of machine-
generated files in the docs. John's got
enough to do at the moment. I run it every
time I edit the docs, so I'm happy to continue
fixing broken links as they appear.
Trevor
___
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
Le jeudi 06 août 2009 à 11:35 +0100, Trevor Daniels a écrit :
Not until we have @rweb or @rgeneral or whatever it gets called.
At least, that's what the @ref{Setup for MacOS X} are waiting for.
I admit that I could fix the @rprogram{LilyPond-book} link right
now if it was a priority.
Adding cross-references macros in macros.itexi should work out of the
box for HTML splitted pages and Info. For other formats, it will
require some xref-@uref hacky conversion, as I think a web site in one
big HTML or single PDF page doesn't make much sense, does it?
It's a python program. I could send it to
you, but I didn't write it for general use
so I'm not too keen on adding it to the source
tree without some tidying up. There are a
few cludges to get round the lack of machine-
generated files in the docs. John's got
enough to do at the moment. I run it every
time I edit the docs, so I'm happy to continue
fixing broken links as they appear.
Have you tried building docs inside the source tree, then cd into
Documentation/ and run
make check-xrefs
and/or
make fix-xrefs
?
It's currently broken for translations, but it seems to work for docs in
English, e.g. make check-xrefs gives
###
../scripts/auxiliar/check_texi_refs.py --batch \
-I . -I /home/lilydev/git/lily/master/Documentation/out-www
-I /home/lilydev/git/lily/master/Documentation/snippets
-I /home/lilydev/git/lily/master/Documentation/snippets/out-www
../python/auxiliar/manuals_definitions.py
Reading files...
Processing manual ./notation.tely (ruser)
Processing manual ./out-www/internals.texi (rinternals)
Processing manual ./application.tely (rprogram)
Processing manual ./learning.tely (rlearning)
Processing manual ./music-glossary.tely (rglos)
Processing manual ./snippets.tely (rlsr)
Checking cross-references...
./notation/notation-appendices.itely: 939: `Fonts': external ruser x-ref
should be internal
./notation/notation-appendices.itely: 940: `Text encoding': external
ruser x-ref should be internal
./notation/notation-appendices.itely: 981: `Layout interfaces': external
ruser x-ref should be internal
Done: 7137 x-refs found, 3 bad x-refs found, fixed 0.
##
These 3 nits should be fixed automatically by fix-xrefs BTW.
Best,
John
signature.asc
Description: Ceci est une partie de message numériquement signée
___
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
On Thu, Aug 06, 2009 at 01:06:20PM +0200, John Mandereau wrote:
Le jeudi 06 août 2009 à 11:35 +0100, Trevor Daniels a écrit :
Not until we have @rweb or @rgeneral or whatever it gets called.
At least, that's what the @ref{Setup for MacOS X} are waiting for.
Adding cross-references macros in macros.itexi should work out of the
box for HTML splitted pages and Info. For other formats, it will
require some xref-@uref hacky conversion, as I think a web site in one
big HTML or single PDF page doesn't make much sense, does it?
No; I think the pdf manuals should link to lilypond.pdf (renamed
from general.pdf), and the info manuals should link to
lilypond.info (again with the renaming). The whole point about
remaking the website in texinfo was that we *could* generate it in
whatever format people wanted. :)
As for the one big HTML docs, I'd suggest that it @ref to the
splitted general html. That said, I've never been a fan of the
one big html stuff, so if anybody who uses that wants to argue
that we *should* create one big general.html... and if that person
wants to patch the init script or whatever so that we generate
such a file... then I won't object.
make check-xrefs
Cool!
I need to spend 1-2 more days on the AU, but then I'll finally
start my CG review. I'll definitely add this at that point.
Cheers,
- Graham
___
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
2009/8/6 Graham Percival gra...@percival-music.ca: As for the one big HTML docs, I'd suggest that it @ref to the splitted general html. That said, I've never been a fan of the one big html stuff, so if anybody who uses that wants to argue that we *should* create one big general.html... and if that person wants to patch the init script or whatever so that we generate such a file... then I won't object. I'm not sure to understand it well. A reader of the big page does not want him to be taked off from there to a splitted page, but rather stay on the document him/her is reading. Unless we could easily switch between big to splitted and vice versa just by means of 1-click(TM) -- Francisco Vila. Badajoz (Spain) www.paconet.org www.csmbadajoz.com ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
On Thu, Aug 06, 2009 at 01:46:33PM +0200, Francisco Vila wrote: 2009/8/6 Graham Percival gra...@percival-music.ca: As for the one big HTML docs, I'd suggest that it @ref to the splitted general html. That said, I've never been a fan of the one big html stuff, so if anybody who uses that wants to argue that we *should* create one big general.html... and if that person wants to patch the init script or whatever so that we generate such a file... then I won't object. I'm not sure to understand it well. A reader of the big page does not want him to be taked off from there to a splitted page, but rather stay on the document him/her is reading. Unless we could easily switch between big to splitted and vice versa just by means of 1-click(TM) The question is this: suppose you're reading AU x.y, and it says for information about setting up lilypond for command-line use on MacOS X, see __MacOS X__. (__MacOS X__ is currently on the new website, Downloads-MacOS X) Now, if the user clicks on __MacOS X__, should he be taken to a splitted html page (i.e. exactly what you see on the new website), or should he be taken to a one big html page version of the new website? Either way, he will be taken away from his current document if he clicks on the link. Cheers, - GRaham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am Donnerstag, 6. August 2009 13:46:33 schrieb Francisco Vila: 2009/8/6 Graham Percival gra...@percival-music.ca: As for the one big HTML docs, I'd suggest that it @ref to the splitted general html. No, big pages should link to the other big pages. That's how the current .init file is supposed to work. If it doesn' t, then that' s a bug in the script and needs to be fixed. That said, I've never been a fan of the one big html stuff, so if anybody who uses that wants to argue that we *should* create one big general.html... Why one large file? I thought it should be one large file per manual, with the xrefs going between those large files. and if that person wants to patch the init script or whatever so that we generate such a file... then I won't object. I'm not sure to understand it well. A reader of the big page does not want him to be taked off from there to a splitted page, but rather stay on the document him/her is reading. Yes, that' s how the script is supposed to work. Links within the manual should point to the anchor in the same file, xrefs to other manuals point to the anchor in the other big file. Or am I misunderstanding what is being said? Cheers, Reinhold - -- - -- Reinhold Kainhofer, reinh...@kainhofer.com, http://reinhold.kainhofer.com/ * Financial Actuarial Math., Vienna Univ. of Technology, Austria * http://www.fam.tuwien.ac.at/, DVR: 0005886 * LilyPond, Music typesetting, http://www.lilypond.org -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) iD8DBQFKesPVTqjEwhXvPN0RAk7cAKCR1IdZHvWo5AZEEoOSU/Pp6JkncQCeOUJV /6zJdkWBq3Okb7+kvCVvUo8= =txGx -END PGP SIGNATURE- ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
Le jeudi 06 août 2009 à 13:51 +0200, Reinhold Kainhofer a écrit : No, big pages should link to the other big pages. That's how the current .init file is supposed to work. If it doesn' t, then that' s a bug in the script and needs to be fixed. But does the web site in one large page makes sense? Why one large file? I thought it should be one large file per manual, with the xrefs going between those large files. You think right, IIUC Graham and I never meant anything else. Or am I misunderstanding what is being said? You 're right in theory, but from a practical point of view, current web-texi2html.init makes big page without navigation bars, and I'm not keen on a web site being on big page, so I just disabled compilation of general.texi in one big page. Maybe we'll be convinced that a big page for the web site is a good site, but then I have no time (i.e. I don't want) to hack any Texi2HTML init file until the rest of the web site and docs infrastructure including translations is in a good shape. Best, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
John Mandereau wrote Thursday, August 06, 2009 12:06 PM Le jeudi 06 ao=C3=BBt 2009 =C3=A0 11:35 +0100, Trevor Daniels a =C3=A9crit = : Have you tried building docs inside the source tree? No; I'm on Windows Vista, so building isn't an option, is it? I generated my own scripts so I can have my texinfo syntax and crossref links machine-checked. Then I feel happy about editing docs and pushing doc commits. It also means I can check individual .itely files rather than building the whole of the documentation. This takes only 1-2 minutes, which is very efficient when honing doc edits. Checking cross-references... ./notation/notation-appendices.itely: 939: `Fonts': external ruser x-ref should be internal ./notation/notation-appendices.itely: 940: `Text encoding': external ruser x-ref should be internal ./notation/notation-appendices.itely: 981: `Layout interfaces': external ruser x-ref should be internal Done: 7137 x-refs found, 3 bad x-refs found, fixed 0. Aah; my checker doesn't check that. Good catch. I'll add that refinement, I think it should be easy (if that term can apply to anything to do with LilyPond :) These 3 nits should be fixed automatically by fix-xrefs BTW. Good. In that case I'll leave them for someone else. I'll test out my change before I pull again to be sure it picks these up. Best, John Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
Le jeudi 06 août 2009 à 14:48 +0100, Trevor Daniels a écrit : No; I'm on Windows Vista, so building isn't an option, is it? No, but you can still run check-xrefs and fix-xrefs, but it will complain about missing files markup*.tely, internals.tely and so on. Good. In that case I'll leave them for someone else. I'll test out my change before I pull again to be sure it picks these up. Try to run make fix-xrefs anyway, I would not be surprised if it fixed these errors. Best, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
Le jeudi 06 août 2009 à 04:18 -0700, Graham Percival a écrit : make check-xrefs I need to spend 1-2 more days on the AU, but then I'll finally start my CG review. I'll definitely add this at that point. Documentation]$ grep check-xrefs contributor/* contributor/doc-work.itexi:for check-xrefs and fix-xrefs targets in 'make help' output. Note HTH, John signature.asc Description: Ceci est une partie de message numériquement signée ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
John, you wrote Thursday, August 06, 2009 3:01 PM No; I'm on Windows Vista, so building isn't an option, is it? No, but you can still run check-xrefs and fix-xrefs, but it will complain about missing files markup*.tely, internals.tely and so on. Good. In that case I'll leave them for someone else. I'll test out my change before I pull again to be sure it picks these up. Try to run make fix-xrefs anyway, I would not be surprised if it fixed these errors. Hhm. I tried to run make once before and gave up after two days. Honestly, it's easier to fix my own program. I've done that already - it now identifies the same three errors. Trevor ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Broken refs
On Thu, Aug 06, 2009 at 03:29:11PM +0200, John Mandereau wrote: Le jeudi 06 août 2009 à 13:51 +0200, Reinhold Kainhofer a écrit : No, big pages should link to the other big pages. That's how the current .init file is supposed to work. If it doesn' t, then that' s a bug in the script and needs to be fixed. But does the web site in one large page makes sense? general.texi is a manual. It happens to be the first manual that people should read, but IMO it's still a manual. My opinion is that we should still produce one large page for this, but I'm not too concerned either way. Why one large file? I thought it should be one large file per manual, with the xrefs going between those large files. You think right, IIUC Graham and I never meant anything else. Yes -- possibly the confusion arose from general.html, by which I meant the one large file for the manual produced by general.texi, rather than the one large file that is generally everything. :) Or am I misunderstanding what is being said? You 're right in theory, but from a practical point of view, current web-texi2html.init makes big page without navigation bars, Sounds fine to me. I suggest that we just go with this and add the @rgeneral links. If somebody wants to hack stuff to get navbars in the large page at a later date, they can do that. Cheers, - Graham ___ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
