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? 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
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.
-Sandra
