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