Guide theme update?

[Horst Gutmann]

Hi Mojca 🙂

On 06.05.19 18:52, Mojca Miklavec wrote:
> Dear Horst,
>
> On Sun, 5 May 2019 at 16:15, Horst Gutmann wrote:
>> I noticed that the main website today (or yesterday) got a little
>> refresh with the bright blue tone being more prominent. Is someone
>> already working on updating the guide's stylesheet to also reflect that
>> change?
> Se the answer by Clemens, as well as
>     https://lists.macports.org/pipermail/macports-dev/2019-May/040674.html
> with a bunch of links to brainstorming documents.


I was laughing quite loudly when I saw that email enter my inbox right
after I had sent mine ^_^


>
>> If not, then I'd also like to update the typography there
>> (larger font size with increased line-height). Would that be OK for you
>> and what would be the process here? (I already found the correct repo on
>> Github and am playing around with the stylesheet).
> I'm not sure if anyone already touched the guide. Improving the guide
> (ignoring the content improvements) would basically consist of three
> semi-independent steps:
>
> (1) We already have a bunch of auto-generated AsciiDoc documents which
> we would like to use as definitive source as soon as possible. At the
> moment the definitive source is DocBook [xml] and that's somewhat
> non-trivial to edit. The conversion to AsciiDoc would need some loving
> care to fix the conversion errors, but this is in fact an excellent
> task for anyone new to MacPorts, and lots of people can contribute to
> fixing such mistakes. With many people helping the conversion could be
> faster.


Thanks! I will dig through the archive here and the repos for the
conversion from DocBook to AsciiDoc. Perhaps I can help out a bit there
before investing time to the stylesheet that is used right now for the
DocBook-sourced HTML 🙂


>
> (2) But before we ask people to start fixing mistakes in AsciiDoc
> documents, it would probably help to have something that more or less
> works (even if having plenty of conversion errors) and deploy a test
> version to some temporary server. And then we need to decide when to
> stop editing XML, run the final conversion to adoc and start fixing
> the mistakes in the new document.
>
> (3) Yes, we definitely need a better style for the guide! The only
> question is whether that style would need to be any different if you
> do conversion to html via DocBook or if you do it directly from
> AsciiDoc (maybe some class names are different etc.), so it might be
> that the change would need to be adjusted once the final switch to
> AsciiDoc is done. It would be really awesome if we could manage to end
> up with (almost) a single css style file that would apply to all the
> pages (main page, guide, news, list of ports, ...) It's somewhat
> suboptimal that the guide would need a completely different css from
> anything else as is the case now.


Definitely! I will try to look up some previous discussions on that
front before doing anything else 🙂


>
>> P.S.: I'm relatively new to macports as I've used it before about a
>> decade ago but just rediscovered it a couple of days ago. I want to help :-)
> I find it amazing that all of a sudden more than four people with some
> designer instinct jumped in to help. We should definitely seize the
> opportunity and do something awesome with the joined forces. Ideally
> with some brainstorming first, followed by a concerted effort to
> improve everything in a uniform, consistent and clear way.
>
> Also: we really really really need a well-written section with "How
> can I help?" (not using that title obviously, but something more
> catchy). When the GSOC period started it was pretty challenging to
> cater all the student and explain to everyone how to get started :) :)
> :). A lot of that should have been obvious from some well-written
> website. We also have a lot of people who find it difficult to write
> and/or test the changes. We should definitely make it easier (and
> easier to find) how to start contributing, either new ports or
> something else, including design changes. We have lots of tickets that
> require trivial changes to a lot of ports, for example, and that could
> be done by any newbie, it's just not all that easy to dig them out.


Once everything is in a single format (or even a single repository) then
creating such guides should become much easier.

Thanks!

Cheers,
Horst


>
> Mojca