Re: multiple online manual versions
On 30 Jan 2022 15:15, Karl Berry wrote: > > https://www.gnu.org/software/automake/manual/index-full.html > > It's better, but how about a non-blank line? > > (does obey table cells? I'm never sure.) > > Obviously we're getting down to trivialities, feel free to ignore :). i actually tested that locally first and thought it looked just awful. on my system, the empty cell is 16px tall (8px padding × 2). makes it 37px, same height as existing rows. makes it 56px, almost twice as large as an existing row. if you have Chrome, should be easy to edit the page and make live tweaks :). > so i guess once gnulib merges my update, > > If nothing happens soon, let me know and I can commit that update. > (I'd do it now but some kind of network problem, apparently at the FSF > end ...) the gnulib folks merged quickly, so i pushed the update to all the pages, and did an update on our side in the git tree. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
> https://www.gnu.org/software/automake/manual/index-full.html It's better, but how about a non-blank line? (does obey table cells? I'm never sure.) Obviously we're getting down to trivialities, feel free to ignore :). so i guess once gnulib merges my update, If nothing happens soon, let me know and I can commit that update. (I'd do it now but some kind of network problem, apparently at the FSF end ...) --thanks, karl.
Re: multiple online manual versions
On 29 Jan 2022 15:56, Karl Berry wrote: > https://www.gnu.org/software/automake/manual/index-full.html > > It looks nice, but the plethora of versions becomes rather an > undifferentiated mass. Maybe make each major release its own > , as in: > > Automake 1.16 releases: > > 1.16* versions > > > Automake 1.15 releases: > > 1.15* versions > > > Just to break it up a little. hmm, i put a blank row inbetween the major versions instead. if they're separate tables, then the column & table widths aren't maintained between tables, so you end up with slightly shifted & different sized tables. if you think the blank rows are a bit too tight still, i could easily make them the same height as the other rows by putting a nbsp in. > Also, some simple intro text seems desirable (edit as you see fit): > > Below are links to the manual for all released versions > of GNU Automake. > The current manual > is also available separately. > > And maybe an outro too: > > Above are links to the manual for all released versions > of GNU Automake. > > Wdyt? sure > The copyright at the bottom says 2020. I don't know if that means > gendocs.sh needs updating, or the template, or something on the web > site, but something somewhere should be changed to 2022. Can you check? it's a couple of things gnulib's gendocs template is out of date upstream: https://lists.gnu.org/archive/html/bug-gnulib/2022-01/msg00179.html and our copy is out of date (even before that): automake$ grep Copyright lib/gendocs_template Copyright (C) 2006-2021 Free Software Foundation, Inc. Copyright © 2020 Free Software Foundation, Inc. so i guess once gnulib merges my update, i'll pull it into automake, and commit the changes to all the indexes. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
Hi Mike, https://www.gnu.org/software/automake/manual/index-full.html It looks nice, but the plethora of versions becomes rather an undifferentiated mass. Maybe make each major release its own , as in: Automake 1.16 releases: 1.16* versions Automake 1.15 releases: 1.15* versions Just to break it up a little. Also, some simple intro text seems desirable (edit as you see fit): Below are links to the manual for all released versions of GNU Automake. The current manual is also available separately. And maybe an outro too: Above are links to the manual for all released versions of GNU Automake. Wdyt? i actually regenerated them from scratch rather than extract them Sounds good. The copyright at the bottom says 2020. I don't know if that means gendocs.sh needs updating, or the template, or something on the web site, but something somewhere should be changed to 2022. Can you check? --thanks, karl.
Re: multiple online manual versions
On 28 Jan 2022 16:35, Karl Berry wrote: > i was planning on the full index being maintained here: > https://www.gnu.org/software/automake/manual/index-full.html > > Sounds good. > > >>See the [full version index] for other versions of the manual. > > Good. Maybe something like: > >>See the [full version index] for the manual for older releases of Automake. > > (Since it's not just "versions of the manual", but "versions of the > software". :) > > Not sure. Will be easier to think about seeing the pages i've back filled the manuals from 1.10* to 1.16* and posted the full index, but haven't linked it in anywhere. lmk what you think. https://www.gnu.org/software/automake/manual/index-full.html i actually regenerated them from scratch rather than extract them from the CVS history. partially because i didn't think of that until after i pushed them, and partially because i think the newer manual style looks nicer. compare the older autoconf manual with the latest one. this is due to the tools used to generate the manual rather than the manual content itself. https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.68/autoconf.html https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.71/autoconf.html > actually differ and setup symlinks in case the manual didn't change > between point releases. > > I doubt there are significant changes to the manual for most > point releases, but still, I think it would be confusing to ask for the > manual for 1.16.2 and get the manual for 1.16.1 instead. I think it'd be > best to just do the full thing for any versions published. i guess it's a bit of a moot point. the generation inserts a lot of date stamps, and i'm not super inclined to try and strip them out to determine if things have changed. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
i was planning on the full index being maintained here: https://www.gnu.org/software/automake/manual/index-full.html Sounds good. >>See the [full version index] for other versions of the manual. Good. Maybe something like: >>See the [full version index] for the manual for older releases of Automake. (Since it's not just "versions of the manual", but "versions of the software". :) Not sure. Will be easier to think about seeing the pages actually differ and setup symlinks in case the manual didn't change between point releases. I doubt there are significant changes to the manual for most point releases, but still, I think it would be confusing to ask for the manual for 1.16.2 and get the manual for 1.16.1 instead. I think it'd be best to just do the full thing for any versions published. --thanks for all, karl.
Re: multiple online manual versions
On 27 Jan 2022 15:21, Karl Berry wrote: > per your request, the default is unchanged. > > I understand (and thanks), but my question was about the "table" > (whether it's actually a or not): > > * (Feb 2018) GNU Automake 1.16 (HTML PDF) > * (Dec 2014) GNU Automake 1.15 (HTML PDF) > * (Jun 2013) GNU Automake 1.14 (HTML PDF) > > On what page were you going to put this table of all available manual > versions? the main index today (and will continue to be) here: https://www.gnu.org/software/automake/manual/ which of course implicitly is: https://www.gnu.org/software/automake/manual/index.html i was planning on the full index being maintained here: https://www.gnu.org/software/automake/manual/index-full.html and then the index.html would contain a link at the end like: You can buy printed copies of some manuals (among other items) from the Free Software Foundation; this helps support FSF activities. >>See the [full version index] for other versions of the manual. (This page generated by the gendocs.sh script.) but i'm completely open to whatever here (naming/grammar/etc...). > BTW I still think it's more useful to have the manual for the latest > 1.xx.y release of each 1.xx than the original. Why propagate known-old > information in preference to newer? sure, doesn't matter that much to me. i was going to see how often they actually differ and setup symlinks in case the manual didn't change between point releases. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
per your request, the default is unchanged. I understand (and thanks), but my question was about the "table" (whether it's actually a or not): * (Feb 2018) GNU Automake 1.16 (HTML PDF) * (Dec 2014) GNU Automake 1.15 (HTML PDF) * (Jun 2013) GNU Automake 1.14 (HTML PDF) On what page were you going to put this table of all available manual versions? BTW I still think it's more useful to have the manual for the latest 1.xx.y release of each 1.xx than the original. Why propagate known-old information in preference to newer? tbh the only reason i'd prefer a table is for the column alignment. Sure. Fine by me. However it works out best. Thanks. -k
Re: multiple online manual versions
On 26 Jan 2022 19:50, Karl Berry wrote: > so the default manual/ landing page & manual will be unchanged from today > other than having a link to the full versioned index > > What url/filename are you thinking for the "full versioned index"? per your request, the default is unchanged. e.g. the one-page html will be as it is today: https://www.gnu.org/software/automake/manual/automake.html we'll also have a copy at (no redirects or symlinks): https://www.gnu.org/software/automake/manual/1.16/automake.html when 1.17 is released, the 1.16/ files won't change, but the base ones will like they are today. e.g. this will be 1.17: https://www.gnu.org/software/automake/manual/automake.html > GNU Automake 1.16 > ... vs. ... > Feb 2018 > GNU Automake 1.16 > HTML > PDF > > I doubt the old manuals will get a tremendous amount of use, so one line > per version seems sufficient to me, vs. a table. But I have no objection > either way. > > OTOH, the date and the direct link to the html seem like the most > interesting information (more so than the PDF). Could be something like: > > GNU Automake 1.16 > - Feb 2018 > - HTML > > > But I don't feel strongly about it. Whatever seems sensible. It might > take seeing the page with a few versions actually done before it's clear > what's best. tbh the only reason i'd prefer a table is for the column alignment. otherwise i would just go with something like: * (Feb 2018) GNU Automake 1.16 (HTML PDF) * (Dec 2014) GNU Automake 1.15 (HTML PDF) * (Jun 2013) GNU Automake 1.14 (HTML PDF) in a non-monospace font, the dates will throw things off slightly. if we add the 1.16.x point releases, then it gets even worse. the slightly OCD in me hates scanning lists vertically based on a field (the version) and dealing with horizontal style shifts at the same time. but should be able to generate a test page with the diff forms and we can make a decision after seeing them in action. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
* i'm assuming that we don't want to modify lib/gendocs_template since it's synced with upstream gnulib For sure. so the default manual/ landing page & manual will be unchanged from today other than having a link to the full versioned index What url/filename are you thinking for the "full versioned index"? GNU Automake 1.16 ... vs. ... Feb 2018 GNU Automake 1.16 HTML PDF I doubt the old manuals will get a tremendous amount of use, so one line per version seems sufficient to me, vs. a table. But I have no objection either way. OTOH, the date and the direct link to the html seem like the most interesting information (more so than the PDF). Could be something like: GNU Automake 1.16 - Feb 2018 - HTML But I don't feel strongly about it. Whatever seems sensible. It might take seeing the page with a few versions actually done before it's clear what's best. --thanks, karl.
Re: multiple online manual versions
i can work with this so plan is to update maintainer/maint.mk: * web-manual will insert a link to the full versioned index in the index.html that gendocs.sh produces * i'm assuming that we don't want to modify lib/gendocs_template since it's synced with upstream gnulib * web-manual-update will also rsync a copy of the manual to manual// * web-manual-update will update the full versioned index to include so the default manual/ landing page & manual will be unchanged from today other than having a link to the full versioned index then i can manually backfill older versions, add the initial full versioned index page, and link it from the current index.html which leaves the last bikeshed: what form to use for the full versioned page. if we have it link to each version's landing page, that might side step some debate. so it'd look like: GNU Automake Manuals GNU Automake 1.16 GNU Automake 1.15.1 GNU Automake 1.15 GNU Automake 1.14.1 ... if we wanted to get fancy we could inline common targets like HTML/PDF, but i'd be fine leaving it at an too. not exactly a common flow. Date Version HTML PDF Feb 2018 GNU Automake 1.16 HTML PDF ... -mike signature.asc Description: PGP signature
Re: multiple online manual versions
* the current page, but with an entry/link like "For older manuals, please see this index." Agreed this is preferable. Not a fan of the gcc index page. changes to the manual the rename or reorder chapters, we're breaking those historical links. Reordering isn't a problem; that doesn't break links. Renaming nodes is what breaks links. And the answer is, 1) don't do it, and 2) if you feel you simply must, leave an @anchor behind, and then existing links will not be broken. Anyway, the manual hardly changes nowadays, so it's not an issue in practice. To me, the redirection to a versioned url a la autoconf often leads to the wrong behavior in the other direction: typically people want to link or refer to the current version of node Foobar (whatever version it might be), but it's too much trouble to do when you end up getting redirected. So it doesn't happen, and then X years now people still think autoconf-2.68, for example, is current because that's what the link say. (Rather like bugs.gnu.org/ being preferred, but since that redirects, hardly anyone uses it and it's just manual labor to do so. But I digress.) any other manual/ access would redirect to the latest version. that way we don't break links already out in the wild. Agreed we certainly must not break existing links. But I'd rather have a copy as the unversioned/canonical page than forced redirection in all cases. Both canonical and versioned urls are useful. https://www.gnu.org/software/automake/manual/1.15/ https://www.gnu.org/software/automake/manual/1.16/ (or if you prefer, 1.15.x and such) If not publishing all versions, it would seem better to me to publish the latest version of the manual for any given 1.x, not the first version. I.e., 1.13.4, 1.14.1, 1.15.1, 1.16.5. I don't see that there's anything especially magical about the "non-dot" releases like 1.15, although I have no objection to publishing those too. --thanks, karl.
Re: multiple online manual versions
On 18 Jan 2022 19:27, Karl Berry wrote: > Having multiple versions of the manual online sounds all to the good to > me. As long as it's being done at all, I wouldn't hesitate to put up > the manuals for every release, not just the major releases. For 1.16.x, > I'm afraid I rather broke the previous rules for major releases anyway. > > https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-/ > > What I don't like about this approach is that it redirects from the > generic url to the versioned url. Also, the /savannah-checkouts/ seems > pretty ugly. > > I think it would be cleaner to create and commit > /automake/manual-/ for whatever s desired. > Could probably get them out of CVS. > > Then automake/manual/ could remain unchanged, as a copy of the > current . FWIW ... --best, karl. i agree that automake/manual/ should be canonical and the main entry point to the documentation. what should that page look like ? i see two ways: * the GCC method where it's a quick index of every version. great for referencing, but i think might put too much emphasis on multiversion. * the current page, but with an entry/link like "For older manuals, please see this index." and that takes you to the full version index akin to what GCC is using. this does a good job of steering people into the latest version without them thinking about it. in terms of layout after that, i'm of two minds. on one hand, i agree that it's kind of ugly that you're always redirected to the versioned one, and there's never a canonical manual/ base. but on the other, if people are copying & pasting links to the manual, everytime we make changes to the manual the rename or reorder chapters, we're breaking those historical links. if it always redirected to a versioned URL, people would be more likely to copy & paste links that are stable. so i would lean towards everything being anchored/entered here: https://www.gnu.org/software/automake/manual/ we'd have the curated landing page & full versioned index in there. the versions would be subdirs rather than parallel so as to keep the higher automake/ dir a bit tidy. so: https://www.gnu.org/software/automake/manual/1.15/ https://www.gnu.org/software/automake/manual/1.16/ (or if you prefer, 1.15.x and such) any other manual/ access would redirect to the latest version. that way we don't break links already out in the wild. -mike signature.asc Description: PGP signature
Re: multiple online manual versions
Having multiple versions of the manual online sounds all to the good to me. As long as it's being done at all, I wouldn't hesitate to put up the manuals for every release, not just the major releases. For 1.16.x, I'm afraid I rather broke the previous rules for major releases anyway. https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-/ What I don't like about this approach is that it redirects from the generic url to the versioned url. Also, the /savannah-checkouts/ seems pretty ugly. I think it would be cleaner to create and commit /automake/manual-/ for whatever s desired. Could probably get them out of CVS. Then automake/manual/ could remain unchanged, as a copy of the current . FWIW ... --best, karl.
Re: multiple online manual versions
On Tue, Jan 18, 2022 at 8:14 AM Mike Frysinger wrote: > currently the automake website only hosts one manual version -- the latest. > when working with older code bases, especially when trying to update them > to newer versions, it can be helpful to have the older manual available to > quickly refer to. can we do this for automake ? i'm thinking of just the > major series (1.11, 1.12, etc...), not the patchlevel (1.16.1, 1.16.2). > > this is pretty common with other projects that have major releases and are > heavily developer oriented. for example: > * autoconf > https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-/ > * gcc > https://gcc.gnu.org/onlinedocs/ > * binutils > https://sourceware.org/binutils/docs-/ > > the autoconf style should be pretty easy to replicate since it's using the > same infrastructure as automake: > https://web.cvs.savannah.gnu.org/viewvc/autoconf/autoconf/manual/ Makes sense.
multiple online manual versions
currently the automake website only hosts one manual version -- the latest. when working with older code bases, especially when trying to update them to newer versions, it can be helpful to have the older manual available to quickly refer to. can we do this for automake ? i'm thinking of just the major series (1.11, 1.12, etc...), not the patchlevel (1.16.1, 1.16.2). this is pretty common with other projects that have major releases and are heavily developer oriented. for example: * autoconf https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-/ * gcc https://gcc.gnu.org/onlinedocs/ * binutils https://sourceware.org/binutils/docs-/ the autoconf style should be pretty easy to replicate since it's using the same infrastructure as automake: https://web.cvs.savannah.gnu.org/viewvc/autoconf/autoconf/manual/ -mike signature.asc Description: PGP signature
