Hello Marcel, On 2016-10-09 15:53, Marcel Bischoff wrote: > As Ryan has identified that the online documentation needs work, I'm > hereby volunteering to give it a go. Since there appear to be quite > specific views on how everthing here needs to be, I'm asking in advance: > > - Is that in everyone's interest?
Of course! :-) > - Is there already someone working on it? We have a new help system on trunk. Each command has a separate man page that can be reached with 'port help install' and similar. Eventually these should also end up on on the web, for example at man.macports.org. https://trac.macports.org/wiki/NewHelpSystem The source of the new man pages can be found in base/doc/*.txt in AsciiDoc format: https://trac.macports.org/browser/trunk/base/doc > - Where should the final documentation be located: separate website, > GitHub wiki, GitHub pages, readthedocs.org, something else? The best would be to overhaul/replace https:///guide.macports.org with something new and better structure. The existing guide can be found here: https://trac.macports.org/browser/trunk/doc-new Hosting the site should be the least concern, we have resources for that now. > - In what format should the documentation be written: HTML, Markdown, > TeX, whatever? I prefer Markdown. I think one of the main reasons why nobody likes updating the guide is the DocBook XML syntax. Back in 2009 (sic!), I started the new help system in AsciiDoc, inspired by the git help system. AsciiDoc is more complex than Markdown, but supports syntax elements such as includes and macros, that are very helpful in reusing the some content in multiple pages and keeping the layout consistent. Also, macros can be defined per output device, expanding to specific syntax in roff/html/pdf/etc. I am fine with using Markdown, as it is the dominant markup syntax today. However, it is also very limited, but that might just be enough for the guide. Rainer _______________________________________________ macports-dev mailing list [email protected] https://lists.macosforge.org/mailman/listinfo/macports-dev
