Re: New WIP DUB documentation
On Wednesday, 24 August 2022 at 10:31:55 UTC, Andrey Zherikov wrote: Just throwing an idea: may be dub can support yaml which has comments? The sdl format already supports that, which dub uses. Json is supposed to be deprecated in dub, but obviously works for backwards compatibility. https://sdlang.org/
Re: New WIP DUB documentation
Just throwing an idea: may be dub can support yaml which has comments?
Re: New WIP DUB documentation
On Thursday, 18 August 2022 at 20:00:10 UTC, Bastiaan Veelo wrote: That's already possible, as unrecognised items are ignored. Actually, from next version, dub will start to warn you (in dub.json) about unknown keys. It does catch quite a lot of mistakes, see https://github.com/dlang/dub/pull/2280#issuecomment-1223326664
Re: New WIP DUB documentation
On Thursday, 18 August 2022 at 20:00:10 UTC, Bastiaan Veelo wrote:
That's already possible, as unrecognised items are ignored.
This is however not flexible enough, as comments are not so
much wanted for adding explanations but much more for
commenting out specific parts. It does work sometimes: you can
for example disable `preBuildCommands` by editing it to
`preBuildCommandsDISABLED`. I don't think you can comment out a
dependency this way, and you cannot comment out an item from an
array like
```json
{
"preBuildCommands": [
"step one",
#"step two",
"step three"
]
}
```
-- Bastiaan.
Ok, thank you, got it.
Re: New WIP DUB documentation
On Thursday, 18 August 2022 at 14:00:38 UTC, Martin Tschierschke
wrote:
What about the following idea about **comments for dub.json**:
Allow the key "comment" inside the json file and alter DUB to
remove all "comment" key value pairs at the beginning of
parsing.
So the file is still valid json but comments are possible like
in dub.sdl.
```
{
"comment" : "dub.json can contain comments,too!",
"name": "myproject",
"description": "A little web service of mine.",
"authors": ["Peter Parker", "John Doe"],
"homepage": "http://myproject.example.com;,
"license": "GPL-2.0",
"dependencies": {
"vibe-d": "~>0.9.5"
}
}
```
That's already possible, as unrecognised items are ignored. This
is however not flexible enough, as comments are not so much
wanted for adding explanations but much more for commenting out
specific parts. It does work sometimes: you can for example
disable `preBuildCommands` by editing it to
`preBuildCommandsDISABLED`. I don't think you can comment out a
dependency this way, and you cannot comment out an item from an
array like
```json
{
"preBuildCommands": [
"step one",
#"step two",
"step three"
]
}
```
-- Bastiaan.
Re: New WIP DUB documentation
Am 18.08.2022 um 12:23 schrieb Bastiaan Veelo: ## Hacking on a local copy of a package If your project depends on a package in which you have found a problem, or you would like to experiment with changes to it, you can force Dub to use a local copy of the package by following these steps: 1. Fork the git repository 2. Check out a local clone at `/path/to/the_package` 3. Let Dub know about it: `dub add-local /path/to/the_package` 4. Make Dub ignore any configured release tag, so you'll see the effect of current changes: `dub add-override the_package * /path/to/the_package` Now you can go ahead and play. Once your PR has been merged and released, or you want to revert to upstream, undo your changes by 5. `dub remove-local /path/to/the_package` 6. `dub remove-override the_package *` If have a branch checked out whose latest version tag matches the version selected by your main project, you can skip the `add-override` step, as dub will prefer a repository added with `add-local` over cached ones from the registry. Also, using `add-path` on the parent directory allows you to clone and delete repositories at will, without having to use `add-local` and `remove-local` each time individually.
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:
Hi all, I'm currently working on new revamped DUB
documentation, check it out if you want, it currently contains
most old documentation plus a big bunch of new documentation:
https://docs.webfreak.org/
Looks great!
What about the following idea about **comments for dub.json**:
Allow the key "comment" inside the json file and alter DUB to
remove all "comment" key value pairs at the beginning of parsing.
So the file is still valid json but comments are possible like in
dub.sdl.
```
{
"comment" : "dub.json can contain comments,too!",
"name": "myproject",
"description": "A little web service of mine.",
"authors": ["Peter Parker", "John Doe"],
"homepage": "http://myproject.example.com;,
"license": "GPL-2.0",
"dependencies": {
"vibe-d": "~>0.9.5"
}
}
```
Re: New WIP DUB documentation
On Thursday, 18 August 2022 at 10:23:35 UTC, Bastiaan Veelo wrote: ## Hacking on a local copy of a package If your project depends on a package in which you have found a problem, or you would like to experiment with changes to it, you can force Dub to use a local copy of the package by following these steps: 1. Fork the git repository 2. Check out a local clone at `/path/to/the_package` 3. Let Dub know about it: `dub add-local /path/to/the_package` 4. Make Dub ignore any configured release tag, so you'll see the effect of current changes: `dub add-override the_package * /path/to/the_package` Now you can go ahead and play. Once your PR has been merged and released, or you want to revert to upstream, undo your changes by 5. `dub remove-local /path/to/the_package` 6. `dub remove-override the_package *` -- Bastiaan. You can also simply to modify the tree in .dub or %appdata% and afterwards copy-paste the change to a git clone. It's more dangerous, but I think it's more straighforward too.
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote: Hi all, I'm currently working on new revamped DUB documentation, check it out if you want, it currently contains most old documentation plus a big bunch of new documentation: https://docs.webfreak.org/ Thank you for doing this! Not sure if this would be the right place, or if it is addressed already, but I repeatedly find myself looking for the right way to use a local checkout of a package instead of the dub registry, because I keep forgetting. It would be nice to have a section like (assuming I got it right): ## Hacking on a local copy of a package If your project depends on a package in which you have found a problem, or you would like to experiment with changes to it, you can force Dub to use a local copy of the package by following these steps: 1. Fork the git repository 2. Check out a local clone at `/path/to/the_package` 3. Let Dub know about it: `dub add-local /path/to/the_package` 4. Make Dub ignore any configured release tag, so you'll see the effect of current changes: `dub add-override the_package * /path/to/the_package` Now you can go ahead and play. Once your PR has been merged and released, or you want to revert to upstream, undo your changes by 5. `dub remove-local /path/to/the_package` 6. `dub remove-override the_package *` -- Bastiaan.
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote: Hi all, I'm currently working on new revamped DUB documentation, check it out if you want, it currently contains most old documentation plus a big bunch of new documentation: [...] Looks go to be a big improvement. Some of the paragraphs on this page are a bit long and might need to get broken up. https://docs.webfreak.org/cli-reference/dub/
Re: New WIP DUB documentation
On Tuesday, 16 August 2022 at 08:13:08 UTC, Sönke Ludwig wrote: Looking good, having SDL+JSON on the same page is especially nice and something I've been wanting to fix for a while. Also definitely a good idea to use a static generator now that the documentation is separate. One question, though - do you generate the CLI documentation from the DUB sources, or is that manual work? for the CLI documentation I modified the man generator to output markdown instead of man formatting, still need to PR that
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote: Hi all, I'm currently working on new revamped DUB documentation, check it out if you want, it currently contains most old documentation plus a big bunch of new documentation: [...] Looks really great. Thanks for doing this.
Re: New WIP DUB documentation
Looking good, having SDL+JSON on the same page is especially nice and something I've been wanting to fix for a while. Also definitely a good idea to use a static generator now that the documentation is separate. One question, though - do you generate the CLI documentation from the DUB sources, or is that manual work?
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote: [SNIP] I like the idea, making dub easier to learn for those who are unfamiliar, but I have a singular request: Could you do a section on setting up a copy of dub-registry?
Re: New WIP DUB documentation
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote: [...] I like it! Can anything be done about the width of the `buildOptions` table though? The whole page takes up about about half of my horizontal screen real estate, yet the "corresponding GDC flags" column is still partially out of view until I scroll right. I'm on a laptop so I can do horizontal scrolls by gesture, but I imagine a user with only vertical scrolling has to navigate all the way down to the bottom of the table to get the horizontal scroll bar to show? (I don't know how to solve it neatly but I thought I'd mention it.)
Re: New WIP DUB documentation
It is pretty awesome, a lot easier to digest and get into!
