On Thu, Nov 4, 2021 at 11:05 AM Martin Liška <mli...@suse.cz> wrote: > > On 11/2/21 16:56, Sandra Loosemore wrote: > > On 11/2/21 9:20 AM, Martin Liška wrote: > >> On 11/2/21 15:48, Sandra Loosemore wrote: > >>> On 11/2/21 2:51 AM, Martin Liška wrote: > >>>> On 11/2/21 00:56, Sandra Loosemore wrote: > >>>>> I'll wait a couple days before committing these patches, in case > >>>>> anybody wants to give some feedback, especially on technical issues. > >>>> > >>>> Hello. > >>>> > >>>> Appreciate the work you did, but the patchset will cause quite some > >>>> conflicts > >>>> in the prepared Sphinx migration patch I've sent to the mailing list :/ > >>>> Anyway, I will rebase my patches. For the future, are you planning doing > >>>> similar > >>>> documentation reorganization for a manual? Based on discussion with > >>>> Gerald, I hope > >>>> we can finish the transition before the end of this year. > >>> > >>> My understanding was that, if this conversion is indeed going to happen, > >>> it's going to be automated by scripts? > >> > >> Exactly, but the conversion needs some manual post-processing that I've > >> already done. > >> > >>> I hadn't seen any discussion of it on the list for months and thought > >>> the whole idea was on hold or scrapped, since it hasn't happened yet. > >> > >> There was almost no response, so that's why I contacted Gerald about help. > > > > I have to admit that I was buried in technical work at the time of the > > previous discussion (in fact, the Fortran things I am now trying to > > document), and didn't have time to look at the proposed changes in any > > detail. I have wondered, though, why it's necessary to do this change.... > > if people don't like the way Texinfo formats output, can't we fix Texinfo? > > That's a reasonable question. Well, I believe the technical dept (feature > set) of Texinfo (compared to more modern tools) is significant and I don't > want > to spend my time hacking a HTML, Javascipt and so on. Moreover, Sphinx is > massively used: https://www.sphinx-doc.org/en/master/examples.html > and the tool is actively developed. > > > > Or hack it to translate the sources to something like DocBook instead, and > > then adopt that as our source format? I can write documentation in any > > markup format, but it seems to me that structured XML-based formats are a > > lot more amenable to scripted manipulation than either Texinfo or > > restructured text. If the rest of the community is set on Sphinx, I'm fine > > with that, but I kind of don't see the point, myself. :-S > > We think with David that DocBook is too complicated and a markup is a better > choice (from that perspective, Texinfo is fine). > > > > >>> In any case it does not seem reasonable to freeze the current Texinfo > >>> docs for months while waiting for it to happen, especially as we are > >>> heading into the end of the release cycle and people are finishing up > >>> changes and new features they need to document. > >> > >> Sure, I can easily rebase normal changes, but you are suggesting a > >> complete redesign/renaming. It's going to take me some time, > >> but I'll rebase my patches. > > > > Well, what I've done is hardly a "complete" redesign/renaming of the > > Fortran manual -- I've barely scratched the surface on it. My main goal > > was just to update the bit-rotten standards conformance sections, which > > were unfortunately spread among multiple places in the document. I did > > consolidate those few sections, but I did not make any big-picture changes > > to the organization of the manual, and I have not even reviewed any other > > parts of it for accuracy or relevance. I'd been thinking about making a > > pass to do some copy-editing things, like making sure all chapter/section > > titles use consistent title case capitalization, but I will hold off on > > that if it's going to cause problems. > > I see, thanks for doing that.
Sandra - please go forward with improving the manual with the current texinfo setup. There's zero reason to hold off on improving user level documentation. Thanks, Richard. > Martin > > > > > -Sandra >
