kicad-developers team mailing list archive

[Martijn Kuipers <martijn.kuipers@xxxxxxxxx>]

If separate, you could update it more frequently. Just take care it is
understandable for which lkicad version it applies.

Local docs is where I look first.

Just my 2cents.
Martijn

A quarta, 19/01/2022, 05:44, Ajith Narayanan <ajith@xxxxxxxxxxxx> escreveu:

> Greetings!
>
> KiCad's documentation is in a standard source format (asciidoc) from which
> HTML/CSS are generated. Currently 'KiCad Help' just kicks off a browser
> pointing it to the local file(s) (e.g.
> /usr/share/doc/kicad/help/en/kicad.html). This is quite clean.
>
> In other words, KiCad already has a (version controllable) single source
> documentation that can generate both the locally installable documentation,
> as well output suitable to be published online on the web.  (Their styles
> could be different, say by applying different CSS -- many possibilities in
> the pipeline).
>
> A single source along with a capable rendering workflow with multiple
> targets (local documentation, web, epub, PDF via a LaTeX pipeline) etc are
> all enabled by this approach.
>
> I don't think there is anything to be gained by discontinuing local
> documentation. The disk usage is very small, tiny by today's standards, and
> the pipeline / workflow  is pretty much the same, it already exists.
>
> If at all somebody wants to be free of local documentation, then:  this
> need can be served by making kicad-doc-XXX a separately installable
> package, with optional dependency indicated. When not installed, KiCad Help
> would send the browser to the online documentation site (taking care to
> match the KiCad version to the URL to the correct documentation version). I
> feel, on that help page, we should advise the user to install the package
> locally if she would like to have local access.
>
> That's just my input.
>
> --Ajith
>
>
> On Wed, 19 Jan 2022 at 02:13, Jon Evans <jon@xxxxxxxxxxxxx> wrote:
>
>> We have decided to update the online documentation in a rolling fashion,
>> meaning that new changes go "live" pretty quickly after being approved and
>> merged.
>>
>> The version that is bundled with the application is a snapshot in time
>> (at the point that software release was made).
>>
>> I think moving to an online-only help system is actually a good idea and
>> I've talked about this before some -- it would also make it easier to
>> improve the formatting of the documentation, since we would have only one
>> output format (HTML/CSS) to deal with.
>>
>> The main reason to include offline documentation (other than "because
>> that's how it's always been done with KiCad") is to provide documentation
>> that is accessible if the user's computer doesn't have an internet
>> connection.  I'm not sure that this is a very important feature in today's
>> world.
>>
>> -Jon
>>
>> On Tue, Jan 18, 2022 at 1:05 PM Tom A. <ta8936@xxxxxxxxx> wrote:
>>
>>> I don't have view at all, not really a software engineer so may take a
>>> bit of spamming with some questions that may be quite obvious to others.
>>>
>>> My first question is why in the software Help section is so dated and
>>> online version much more up to date? It seems you can access online version
>>> from the software, so why to include old (probably no more relevant)
>>> documentation?
>>>
>>> Regards,
>>> Tomas
>>>
>>> On Tue, 18 Jan 2022, 17:17 Jon Evans, <jon@xxxxxxxxxxxxx> wrote:
>>>
>>>> I don't personally see the point of spamming the list with back and
>>>> forth about setting up Git/Gitlab, installing dependencies, etc.
>>>>
>>>> But, I am not opposed to it if others don't care.
>>>>
>>>> -Jon
>>>>
>>>> On Tue, Jan 18, 2022 at 12:02 PM Marco Ciampa <ciampix@xxxxxxxxxx>
>>>> wrote:
>>>>
>>>>> On Tue, Jan 18, 2022 at 09:10:22AM -0500, Jon Evans wrote:
>>>>> > Hi Tomas,
>>>>> >
>>>>> > I've been loosely coordinating documentation updates for V6.  There
>>>>> are not
>>>>> > very many other people working on it.  We'd be happy to have your
>>>>> help.
>>>>> > If you contact me off-list I can help you get set up to make changes
>>>>> and we
>>>>> > can figure out where you'd like to start.
>>>>>
>>>>> I don't want to be rude but I do not understand. This list is almost
>>>>> silent. For sure some docs dev set-up instructions will not hurt
>>>>> anybody
>>>>> and perhaps there is something to learn (I bet I'll learn something
>>>>> anyway ...). So please do not discuss that elsewhere. This list was
>>>>> meant
>>>>> also for this.
>>>>>
>>>>> --
>>>>>
>>>>> Saluton,
>>>>> Marco Ciampa
>>>>>
>>>>> _______________________________________________
>>>>> Mailing list: https://launchpad.net/~kicad-developers
>>>>> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>>>> Unsubscribe : https://launchpad.net/~kicad-developers
>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>
>>>> _______________________________________________
>>>> Mailing list: https://launchpad.net/~kicad-developers
>>>> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>>> Unsubscribe : https://launchpad.net/~kicad-developers
>>>> More help   : https://help.launchpad.net/ListHelp
>>>>
>>> _______________________________________________
>> Mailing list: https://launchpad.net/~kicad-developers
>> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~kicad-developers
>> More help   : https://help.launchpad.net/ListHelp
>>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>