Hi, > On 27. Jul 2022, at 19:35, Willow Liquorice <wil...@howhill.com> wrote: > > Hello, > > Yeah, I've done quite a bit of work on that front. I believe I used the > pandoc method in the end to translate it all to (rough) reST. The conversion > isn't perfect: the heading hierarchy is a bit iffy and it completely breaks > the index (a blessing and a curse, Sphinx's indexing is a lot more > sophisticated so rewriting the index would be desirable anyway). >
Ah great. I started with a blank slate and used markdown. I wanted to 1. Weed out and reorganize the docs (The "Installation" chapter is just wrong in all kinds of ways) 2. Use Sphinx and ideally, markdown Both requires quite a lot of manual work. So, I guess we need to decided on what to proceed. But if you say that the pandoc result is workable that is fine with me. I think there are rst to markdown converters for sphinx as well. > I wasn't able to submit any of this because I couldn't find a place to sign > on the Copyright Assignment. > I am not sure I understand "place". Do you mean you did not know where to sign it on the document? (the answer is anywhere) > The Doxygen tidy-up I was doing has stalled out too, because I couldn't get > the neovim macros I wrote for the task to work reliably. They use neovim's > LSP integration to find a symbol in the headers, but they rely on cursor > placement to do that, and the cursor sometimes misses the symbol. When they > work, everything progresses rather quickly because you don't have to wade > through the source code. > > I'm not sure how easy it would be to share those macros, if anyone wants to > help me debug them, but I can at least share the Lua functions and LSP > configuration they use to perform the navigation. Would anyone like to see > them? > Sounds like something that may go somewhere into contrib (the lua script/nvim config). For now, I would like to tackle the handbook first. BR Martin > Best wishes, > Willow Liquorice > > On 27/07/2022 18:01, Schanzenbach, Martin wrote: >> Hi, >> I was wondering if you had started with sphinx/rtd for the handbook already? >> If not, I have played around with it today and already have migrated some >> text and could commit it to gnunet.git or a new repo. >> That would allow anyone to play around and add content. >> But if you are already further, I would stop and not do that :) >> BR >> Martin >>> On 24. May 2022, at 23:19, Willow Liquorice <wil...@howhill.com> wrote: >>> >>> Ah, you can do it through pandoc. I'll bear that in mind and see about >>> adapting it to our repository. >>> >>> On 24/05/2022 22:16, Nikita Ronja Gillmann wrote: >>>> Hi, >>>> qemu did this a while back it seems >>>> On 5/24/22 22:38, Willow Liquorice wrote: >>>>> As an aside, *does anyone know of any tools to convert TeXinfo to reST*? >>>>> This migration is going to be much smoother if there are. >>>> https://patchwork.kernel.org/project/qemu-devel/patch/20200226113034.6741-19-pbonz...@redhat.com/ >>>>> - Willow >>>>> >>>>> On 24/05/2022 18:01, Christian Grothoff wrote: >>>>>> The doxygen configuration file in Git just had an ancient version >>>>>> number. I've fixed that now. The rest was up-to-date ;-). >>>>>> >>>>>> -Christian >>>>>> >>>>>> On 5/23/22 16:24, Willow Liquorice wrote: >>>>>>> Just look at https://docs.gnunet.org/doxygen/html/index.html and you'll >>>>>>> see what I mean. >>>>>>> >>>>>>> - Willow >>>>>>> >>>>>>> On 23/05/2022 15:23, Christian Grothoff wrote: >>>>>>>> I cannot even find a version number on https://docs.gnunet.org/, so >>>>>>>> that's likely not what you are refering to. So where exactly are you >>>>>>>> looking to find documentation for 0.11.x? Likely some code to update >>>>>>>> some location is not working (or was never written, and someone put >>>>>>>> something out manually...). >>>>>>>> >>>>>>>> -Christian >>>>>>>> >>>>>>>> On 5/23/22 16:16, Willow Liquorice wrote: >>>>>>>>> Alright, doc/sphinx it is. >>>>>>>>> >>>>>>>>> The handbook is already intended for two wildly different audiences, >>>>>>>>> what with being both a user's and developer's manual. Having the >>>>>>>>> source code documentation in one place (and possibly better >>>>>>>>> organised) might make it easier to work with, and help keep the >>>>>>>>> Developer's Manual up-to-date. >>>>>>>>> >>>>>>>>> On another note, are the online source docs even up to date? The >>>>>>>>> indicated version on them is 0.11.x, which is several years gone at >>>>>>>>> this point. >>>>>>>>> >>>>>>>>> Best wishes, >>>>>>>>> Willow >>>>>>>>> >>>>>>>>> On 23/05/2022 08:39, Christian Grothoff wrote: >>>>>>>>>> On 5/23/22 00:57, Willow Liquorice wrote: >>>>>>>>>>> Hello again, >>>>>>>>>>> >>>>>>>>>>> Thanks for the info, good to hear that I've got most of it. Setting >>>>>>>>>>> up a branch in my local GNUnet repository, to start experimenting >>>>>>>>>>> with Sphinx, as I write this. Seeing as there's some experience >>>>>>>>>>> with the software in the project already, where would be the most >>>>>>>>>>> sensible place to put the root directory? My thinking is either the >>>>>>>>>>> repository root or the doc folder. >>>>>>>>>> >>>>>>>>>> Definitively doc/, I think doc/sphinx/ would be good. >>>>>>>>>> >>>>>>>>>>> Would it be sensible to migrate to Sphinx throughout the whole >>>>>>>>>>> GNUnet repository? Breathe (https://www.breathe-doc.org/) could >>>>>>>>>>> very well make the transition easy, as I think it would allow us to >>>>>>>>>>> read the Doxygen comments that are already present in the source >>>>>>>>>>> code. >>>>>>>>>> >>>>>>>>>> I'm not sure importing the Doxygen makes sense, that's very >>>>>>>>>> different from the main handbook/tutorial/man-pages both in terms of >>>>>>>>>> style and audience. >>>>>>>>>> >>>>>>>>>> my 2 cents >>>>>>>>>> >>>>>>>>>> Christian >>>>>>>>>> >>>>>>>>>>> Best wishes, >>>>>>>>>>> >>>>>>>>>>> Willow Liquorice >>>>>>>>>>> >>>>>>>>>>> On 22/05/2022 22:27, Christian Grothoff wrote: >>>>>>>>>>>> Hi Willow, >>>>>>>>>>>> >>>>>>>>>>>> We've been using RST/Sphinx for the GNU Taler documentation, and >>>>>>>>>>>> it can generate reasonable TeXinfo. From that experience, I'm not >>>>>>>>>>>> against converting the existing documentation to RST. >>>>>>>>>>>> >>>>>>>>>>>> As far as finding the documentation, I think you found most of it, >>>>>>>>>>>> except maybe the RFC-style specs at https://lsd.gnunet.org/. >>>>>>>>>>>> >>>>>>>>>>>> The handbook is supposed to cover things in depth, with different >>>>>>>>>>>> chapters for installation (for the various platforms), users (by >>>>>>>>>>>> application, explaining what each application can do and how to >>>>>>>>>>>> use it) and developers (by subsystem, explaining how each >>>>>>>>>>>> subsystem is supposed to work). The man-pages are supposed to be >>>>>>>>>>>> for the day-to-day usage when someone wants to quickly look up >>>>>>>>>>>> command-line options. The doxygen is for function-level >>>>>>>>>>>> documentation for developers-only. The tutorial is for >>>>>>>>>>>> newbie-developers, and is a bit dated. Finally, the LSDs are >>>>>>>>>>>> in-depth protocol descriptions for those wanting to do >>>>>>>>>>>> interoperable (re)implementations. >>>>>>>>>>>> >>>>>>>>>>>> I hope that answers your questions and look forward to you >>>>>>>>>>>> improving the documentation! >>>>>>>>>>>> >>>>>>>>>>>> Happy hacking! >>>>>>>>>>>> >>>>>>>>>>>> Christian >>>>>>>>>>>> >>>>>>>>>>>> On 5/20/22 02:21, Willow Liquorice wrote: >>>>>>>>>>>>> I've got some free time on my hands now, and I gave some thought >>>>>>>>>>>>> to improving the readability of the HTML documentation on the >>>>>>>>>>>>> website (which is what the average prospective GNUnet dev is >>>>>>>>>>>>> going to look at). Read the Docs and friends set the standard in >>>>>>>>>>>>> this regard. Having the contents in a sidebar for easy access >>>>>>>>>>>>> (regardless of your location) would be far more convenient than >>>>>>>>>>>>> what's currently available. >>>>>>>>>>>>> >>>>>>>>>>>>> I understand that TeXinfo's HTML generation is a bit simplistic >>>>>>>>>>>>> in the name of compatibility, which, while not a bad thing, >>>>>>>>>>>>> results in a subpar reading experience for the average dev who >>>>>>>>>>>>> will, in all likelihood, be reading the docs on a very capable >>>>>>>>>>>>> modern browser. >>>>>>>>>>>>> >>>>>>>>>>>>> While thinking about how to improve things with TeXinfo, it >>>>>>>>>>>>> occurred to me that, instead of trying to emulate the experience >>>>>>>>>>>>> of using Read the Docs, one could just use Read the Docs! It's >>>>>>>>>>>>> Free Software, after all. I haven't looked into it too deeply, >>>>>>>>>>>>> but if the .texi sources are converted to the reStructuredText >>>>>>>>>>>>> that it accepts, a migration (or use of a similar platform) might >>>>>>>>>>>>> be worth considering. What do the people here think? >>>>>>>>>>>>> >>>>>>>>>>>>> If I'm going to dedicate time to restructuring GNUnet's docs, I >>>>>>>>>>>>> need to know where it all is. I've found four strands of docs in >>>>>>>>>>>>> the repository (Handbook, Tutorial, Doxygen, and man pages), >>>>>>>>>>>>> could someone give me a run-down of the state they're in, how >>>>>>>>>>>>> they relate to one another, and what they're supposed to be for? >>>>>>>>>>>>> Is that everything? >>>>>>>>>>>>> >>>>>>>>>>>>> Thanks, >>>>>>>>>>>>> Willow >>>>>>>>>>>>> >>>>>>>>>>>>> On 01/03/2022 22:52, Christian Grothoff wrote: >>>>>>>>>>>>>> Spam killed this. We already constantly have to delete 'bug >>>>>>>>>>>>>> reports' >>>>>>>>>>>>>> from the Web that were submitted as link spam. A wiki will drain >>>>>>>>>>>>>> resources to keep the spammers out, and at the same time >>>>>>>>>>>>>> experience says >>>>>>>>>>>>>> the contributions will be low quality (it has been tried). >>>>>>>>>>>>>> >>>>>>>>>>>>>> If someone really is capable and invests time into contributing >>>>>>>>>>>>>> to >>>>>>>>>>>>>> documentation, they can pick up Git and send patches. >>>>>>>>>>>>>> >>>>>>>>>>>>>> On 3/1/22 11:12 PM, madmurphy wrote: >>>>>>>>>>>>>>> I don't know if this will be a popular proposal, but I really >>>>>>>>>>>>>>> believe >>>>>>>>>>>>>>> that setting up a self-hosted Wiki could be a very good choice. >>>>>>>>>>>>>>> No >>>>>>>>>>>>>>> complicate git clone, no complaints, just read/edit what you >>>>>>>>>>>>>>> need, and >>>>>>>>>>>>>>> distributed responsibilities about its design and direction. >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> My two cents >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>> >>>>>>>> >>>>>> >>>>> >>> >
signature.asc
Description: Message signed with OpenPGP